[tablespoon]

> The big problem with comments is that they need to be maintained. When the code changes, the comments need to change with it.

> So soon you have the "man with two watches" problem. The code says one thing, and the comments say another. You could fix it, and sometimes you spend that time, but inevitably you also stop reading the comments, since they're not reliable.

When you think about it, function and variable names are comments. Should we not use those because they need to be maintained with the code?

[BurningFrog]

My main solution is to use good function and variable names.

Including - and I had some resistance to this - breaking out a variable or function solely to give something a name that needs describing.

This way you have one source of truth. It can be wrong, but you only update it once, and it never conflicts with itself.

I understand what you mean by "function and variable names are comments". We do use them to describe what the code does. Still, they are actually code :)

[IlliOnato]

Redundancy helps to spot errors. When I see code like

// add vertical scroll bar

addHorizontalScrollBar(...)

I _know_ something is wrong.

Did the comment get out of synch with the code? Or the developer copied-and-pasted the wrong function? Or the function itself is misnamed? I don't know! Let's investigate... and fix whatever happens to be erroneous!

But when I see just

addHorizontalScrollBar(...)

all I know is that a horizontal bar seems to be added (provided the function name reflects its... er... function). I don't know whether it was intended behaviour. If it has not been, nothing indicates this at all.

I've actually caught real bugs this way, multiple times.

[tablespoon]

> My main solution is to use good function and variable names.

The problem with this is that it isn't actually solution. A name can't contain much that's helpful to know about a thing, which should be obvious given how much prose and narrative everyone produces and consumes. The program itself can only tell you what. Names can sometimes hint at intent, but they they're not very good at it (given the incentive for terseness). Comments are good for explaining the "whys" for a thing as well as intent. Those are important things to know when debugging a problem or trying to enhance something.

Comments shouldn't be thought of as the one thing you need to look at to understand some code. You really have to look at a whole constellation of things (comments, implementation, commit history, tribal knowledge) and synthesize them. When you take that approach, even out of date comments can be more useful than no comments.

> I understand what you mean by "function and variable names are comments". We do use them to describe what the code does. Still, they are actually code :)

They're not any more code than comments are. Run an obfuscator and change all names to random strings and everything will still work fine, just like if you ran a program to strip out comments.

[IneffablePigeon]

I agree with elements of both sides here but I do think there's one important difference with function and variable names, which is that they have to match between definition and usage.

If you refactor a function or variable to do something different, often it becomes obvious at the calling/usage site that something isn't quite right any more and the name gets fixed. Just having more instances of it gives you more opportunities to realise you need to fix the name.

It's absolutely not foolproof, you can obviously still have them get out of sync. I do find it's rarer, though, personally.

[nicoburns]

If you use a comment instead of breaking a block of code out into a function, don't you still have one source of truth?