Observation: many comments explaining what the code is doing don't match what the code is doing after a few check-ins. E.G., I've seen variations on
//Add 1 to x
x+=2;
Comments that have the same content as the code but written in English will have code drift problems. But most comments aren't like this; they can provide context or explain what's happening at a higher level, ideally.
But ideally the comments should be executable, as unit tests, making you read them if and only if you break them.
For this to be a tolerable development experience, test as much as you can while keeping your tests away from slow dependencies like networking, DB, disk I/O..., and try to keep tests relevant to what you're modifying executable locally in a few seconds.
Maybe even refactor your app to have dependencies at the top, so that most code doesn't have access to them.
For the kinds of comments that answer the "why", if we could do that, we wouldn't need the actual code in the first place.
> making you read them if and only if you break them.
A good "why" comment is supposed to inform you beforehand, so you can make changes effectively and without introducing extra bugs in the process. Unit tests are more of a safety net.
// in case this is malformed, fix formatting so it will still parse
input = fixInputFormatting(input);
Nothing to raise the blood pressure like a code review question that is literally answered by a comment on the line immediately preceding where they left the question.
input = fixInputFormattingIfMalformed(input);
if (isMalformed(input)) input = fixInputFormatting(input);Which makes me to think that the AI models should be trained on the code evolution of commit chains and not just on isolated snippets of code. That way, the AI could analyze your own commits to detect when a comment becomes outdated.
And once or twice at the top of a weird class/task file/section/..., don't be afraid of being a bit verbose and explain it until it's obvious, and then one more level. Stuff tends to be obvious while you have all the context uploaded in your mental caches - but a year down the line, it'll be rather confusing. Still, having such long comments too much in straight line code tends to make it harder to read.
// This code is weird. I tried doing it the obvious way, but that doesn't work because .. reasons ..
Sometimes, if the code is short, I'll even leave the old/obvious code there for future reference when I look at the weird code and say to myself:
"This is weird! Obviously it should work in this much simpler way.."
# High value orders need to be approved before refund
# Similar logic is also applied elsewhere, this is here
# as a failsafe.
if ticketValue > 500:
emailCustomerSupport(ticket)
else
refundSome programmers use comments (correctly) to explain reasoning and context, some use them to redundantly say what the code already says and some, apparently, use them to apologise.
Sure, sometimes the code is right and the comment is wrong -- but sometimes the comment is right and the code is wrong, in which case the comment just saved me a lot of time.
Comments informs us what are the stuff that the programmer cares enough to write down. When we see a seemingly trivial comment, we may ask: why did they took time to write down that? Did they think there was any subtlety we aren't aware of? Or perhaps they were inexperienced with the language, to the point of having a hard time reading the code they themselves wrote? (if I put this comment on Google, will I find they copy-pasted from Stack Overflow? -- in this case, the comment may be very helpful, if only to track down that [0])
[0] but even better would be an IDE that highlighted code copy-pasted from Stack Overflow, Github repositories, etc
AddsFiveToNum(num) {
return num - 5
A bunch too. So I don't think comments are solely at fault. Self documenting code is only as good as the person who wrote it, and the people who approved it. Sometimes a comment is warranted, sometimes it's not.
I mean, I still won't want "add 1 to x" comments of course.
It's actually completely achievable with today's models to look at the comment and the code immediately after it and see how surprising it is then note the comment could be incorrect.
A single line of Python data analysis code is often worth 20 lines of C++. If you would be willing to add one comment per 20 lines in C++, then nearly every line of your pandas gobbledygook is worth commenting.
Terse code is good, but that doesn’t necessarily mean the comments should be terse (or absent).
But if you're using comments to explain the code, 9/10 you just wrote it in too unreadable way.
Sure, some algorithms are complex enough that some comments are needed to explain the how (that's the 1/10) but in most cases the comments should explain why, not how. So instead it should be
// Add the calibrated skew to compensate for latency
x+=2;
“Don’t get suckered in by the comments-they terribly misleading. Debug only the code. Dave Storer Cedar Rapids, Iowa
Each segment of code should have a diagram, a flow model, psuedo code, and comments. More the better.
If every refactor involves redrawing a bunch of fancy ASCII art, you'll either get less refactors, or outdated comments
"If loop does something" #rev1
"If loop did do something, it now does something twice" #rev2
"If loop doesn't do something, it does something three times" #rev3
"we loop three times because we processing supervariables" #rev4
> you'll either get less refactors, or outdated comments
If so, you're not disciplined enough. If your project is to be handed over down the line, more documentation is better than any and any documentation is better than none.
That's probably the only useful comment I've ever written.
Or in your case not to write comments at all. That's obviously a terrible idea.
I agree with that, but it gets to the point where people police all the comments in a codebase deeming them unuseful. I think, especially in a huge codebase, explaining why there is a certain block of code is very helpful to transfer knowledge.
(Although two would be useful as a signal that something has gone wrong!)
(I don't mean the DocBlock type comments for describing functions and class interfaces, that get compiled into docs.)
To all you downvoters: please do respond with examples of comments that are are counterexamples to what I said!