Beware the Siren Song of Comments
leastastonished.com
Beware the Siren Song of Comments
1–10 of 34 posts
Re: Beware the Siren Song of Comments
#2It would have been helpful if the author explained how this has benefited him in concrete ways, rather than asserting that his way is best and leaving it at that.
Re: Beware the Siren Song of Comments
#3I've found quite the opposite. Most developers hate comments because they represent extra work. That work manifests itself in the creation and upkeep of the code. We've found that addressing comments as part of our code review process made a big difference in keeping things up to date.
Regarding the issue of expressiveness: I never find myself commenting about what is obvious in the code itself. Often I'm writing about some thinking behind why something was done a certain way OR identifying expectations of downstream systems that can't be expressed using code. Code enough in environments where you're interacting with multiple disparate systems and you'll find that some well placed comment providing the broader context for the code is extremely helpful to folks encountering the code the 1st time or to yourself a year later when you're incorporating a new feature and have forgotten about all the concerns wrapped up in the code.
With the todo issue- we require folks to include a JIRA issue number along with the todo. If something was left undone then it needs to be recognized where we manage our backlog and flagged as a technical debt to be addressed.
Re: Beware the Siren Song of Comments
#4With respect to TODOs and FIXMEs in the comments, I use them to mark places I know I will need to go back. Before calling a piece of code done, I grep for TODO and FIXME to make sure I haven't left anything unfinished.
Re: Beware the Siren Song of Comments
#5It would have been helpful if the author explained how this has benefited him in concrete ways, rather than asserting that his way is best and leaving it at that.
Indeed. "I hate reading articles that make abstract arguments, so enough bloviating" Author then proceeded to do exactly that.
The single item I agreed with was the blocked out old code that will never be used again - source control handles that.
Otherwise, what a load of nonsense.
Re: Beware the Siren Song of Comments
#6Thanks Andrew.
I think you missed a key point, or maybe I overlooked it while scanning.
Because modern programming languages allow very long variable and method names, you should be able to construct a "grammar" in your code. That is, the code itself should be able to be read -- and when you read it, it tells you what it does.
So "if CustomerHasALargeAccount then WriteThemASalesLetter()" not only is a piece of code, it's also directly explaining what's going on. As long as you make sure your names are long and explicit enough, your comments and code become one. (Except for some oddball cases)
I like comments while I'm constructing my thoughts. Once I've coded it, I delete the comments. I can also see using comments as sort of a mnemonic for future work.
A lot of good points here. Keep up the blogging!
Re: Beware the Siren Song of Comments
#7This approach works well in only one situation: when your code isn't doing anything substantial in terms of data processing.
For me, comments are best used at explaining _why this is happening_, not what is happening.
By far one of the best examples of code commenting I've seen is the explanation of the L2ARC (the level 2 adaptive cache) in ZFS: http://fxr.watson.org/fxr/source/cddl/contrib/opensolaris/ut... . Most of the ZFS codebase is extremely well documented due to its comments, and it helps a lot having the documentation _in the code_, to provide context (something that commit logs, by default, don't).
Re: Beware the Siren Song of Comments
#8It would have been helpful if the author explained how this has benefited him in concrete ways, rather than asserting that his way is best and leaving it at that.
Indeed. "I hate reading articles that make abstract arguments, so enough bloviating" Author then proceeded to do exactly that. The single item I agreed with was the blocked out old code that will never be used again - source control handles that. Otherwise, what a load of nonsense.
The author forgot to point out that every comment you add has a cost. And there was not enough emphasis that the code can go on without comments if you make the code itself clear.
Rather being nonsense, the article meant to be statement against nonsense.
Re: Beware the Siren Song of Comments
#9> The right place to document [performance] hacks is a commit message.
This advice strikes me as patently insane.
Serious performance hacks often involve subtle interactions among different parts of the code. When that happens, properly documenting them requires explaining what's going on in a line of code, for every line of code, right next to that line of code. Just sticking a wall of text somewhere else entirely and leaving it up to your successor to go find it and figure out how the explanation cross-references with the code is not an adequate alternative.
Re: Beware the Siren Song of Comments
#10"Comments decay. They aren’t compiled, and they’ll never get executed at runtime. If they become out of date or incorrect, no test is going to fail and no user is going to complain. Programmers work around them out of fear that “somebody might need this comment or it might provide some value in the future”, pushing them along far after they’re useful"
The developers who say this are ticking time bombs of laziness on your team.
Comments only "decay" if you don't read them, or if you don't take the 30 seconds to update them when you make a change. And if you're not doing that, then you're not doing your job, because the previous developer left the comment for a reason, and your defeatist philosophy of "comments are useless" is implicitly overriding that developer's judgment. Respect your colleagues enough to at least read what they've written and update it when it's incorrect!
It's pretty disheartening to hear this from a "director of engineering", actually. I expect it from a new grad who has never worked on a team, or with code that has to live for more than a quarterly project, but I want a team leader to be doing everything possible to improve communication amongst team members. That includes compelling them to write and maintain good comments.