I've started to rethink how to approach documentation of code when working with an international team of developers. One of the things I'm starting to realize is that programmers where English is a second language may not find insight in code comments or documentation as useful as the code itself, as reading through and comprehending the code by itself may be easier for reaching the understanding needed, and possibly more concise requirements documents describing what must be accomplished by the program.<p>What types of code comments and documentation do you find useful that you wouldn't be able to find in the code itself, and which ones do you find counterproductive?
Think to your self: When someone reads this later, are they going to ask "Why did they code it this way?" If your answer to that question is not obvious, answer it in a comment. If it is obvious, let the code speak for itself.<p>Sometimes that means explaining the requirements or business reasons that drove a choice. Other times it is, "I'm in crunch mode to get a release out, feel free to improve this when you have time." Both of those will help future coders make a decision whether or not to change the code.
I've gotten into the habit of adding comments for what the code _should_ do in high level terms, as abstracted from the implementation as makes sense, so that the implementation can change to fit whatever may be needed by a neighbouring piece of code. When reading through, I'm more often that not concerned with what the code is trying to do than how it does it, and having the former makes understanding the latter much more clear. Technical prose that describes functions, arguments, and return values rather than variables and the operations done with them is best IMO.
The only time I find myself adding code comments is when something “looks odd,” if that makes sense. Something that looks like it might be a bug or inefficient but has a very specific reasoning for being that way. Otherwise I try my hardest to make code simple, use sane naming for variables/classes/functions, and just document the functions themselves with short doc strings. Type hinting in python3 has made this a lot easier for me as well.
My strongly held opinion which is probably unpopular: code comments are a code smell, with very exceptional exceptions. Prose comments are almost immediately suspect, because they’re almost certainly not maintained alongside the code under comment (presume out of date). Prose comments which describe what something does almost always describe it worse than the code itself, and almost always suggest the code itself is too complex. Prose comments which describe why something was done the non-obvious way it was are potentially very useful, but still fall out of date too easily and should be used sparingly. Code comments that aid automation are better, but only if they’re reliably up to date too.<p>More often than not, a type definition or a smaller function with a descriptive name and predictable properties/parameters serves the purpose of all of these cases much better than a comment would. And when I do write comments, my heuristic for whether it’s valuable is basically “is it longer than a sentence, and can it link to some other reference for future reading?” Secondarily, “did someone ask about this in review and we decided to leave something non-obvious intact?” Not perfect heuristics! But they’ve served me well, especially compared to trying to understand comments which don’t seem to make any sense when I encounter them.
While not strictly code comments, we heavily encourage very thoughtful commit messages. We manage a complex large project, and being able to read back and really understand the motivations behind subtle changes through commit messages has saved the day many times.
> and which ones do you find counterproductive?<p>Now that one's easy: when some joker changes the code and ignores the commentary right above the affected line (I know this is a silly example, because this comment is more-or-less restating what the code does, but I have a hard time distilling the actual cases I encounter at $JOB into a tl;dr)<p><pre><code> // if the list came back empty, warm the local cache
- if (items.isEmpty()) {
+ if (items.size() == 1) {
</code></pre>
I do have <i>some</i> sympathy for not changing the method docs, or class docs, or a completely separate file that describes the code's behavior, but not reading the *but it's right there* drives me bananas
Once in a while I look back at my own code and wish I had a comment to explain what the hell it does. Maybe even a one liner - can be super useful when code it cryptic.<p>I once had a colleague who wrote extra long comments and I felt like it was an overkill (maybe I was intimated!?) and a distraction when reading the code with IDE that cannot hide comments as needed. If you’re a vim user see [0] on hiding comments with fold.<p>[0] <a href="https://www.rtfm-sarl.ch/articles/hide-comments.html" rel="nofollow">https://www.rtfm-sarl.ch/articles/hide-comments.html</a>
I use comments for API documentation in header file libraries, for explaining messy code, and for documenting "state" -- both a reminder of what the program state should be on executing a given line <i>and</i> my mental state when writing it.<p>Example: <a href="https://github.com/torstenvl/cpgtou/blob/master/cpgtou.h" rel="nofollow">https://github.com/torstenvl/cpgtou/blob/master/cpgtou.h</a>
Code comments are incredibly handy when doing code archeology, where your looking to understand the intent behind the code from 10 years ago, rather than treating the code as is as correct.<p>Typically in code archaeology settings, I've been trying to figure out the correct behaviour when something non-visible has changed, and the code as-is isn't trustworthy for whats the right expectation
I disagree. I think about comments after many years working with diverse and distributed teams mainly this way: comments can be ignored.<p>What do I mean by that? Write as many comments as possible. You do not need to read them. However, if you could help at least some people finding the why of some code, you helped them a lot.<p>Also never underestimate how much the human brain forgets in a couple of months. Many devs are blind to the fact, that for every part of code they are working at, a lot more don't.<p>John Woods has it: "Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live. Code for readability." Comments help a lot.<p>Do your teams as well as your future self a favor. ;)
Comments are not useful. They end up becoming misinformation.
Documentation is extremely useful. It becomes a feedback mechanism for thinking about the API.