Making comments less necessary
Compas Pascal posted about how to comment source code. I would argue that good comments are a poor goal.
Comments go stale. This is tough to avoid. When the code gets changed, the comments don’t necessarily follow. The more comments you put in, the faster they get out of sync with what the code actually does.
There are times when comments are necessary; there are things they’re useful for. But whenever possible, you’re better off writing code that doesn’t need comments in the first place.
There are a lot of ways to do this, so I’ll be posting more about it. Meanwhile, what do you think about comments? What do you use comments for? What do you do to write code that doesn’t need comments?
February 10th, 2008 at 2:34 pm
I am in complete agreement with the Compas Pascal post. A chief complaint I have had with most source code is the lack of comments. Why buy components with source if you can’t realistically fix any problem because you don’t understand it? It’s harder to glean design from raw code without any comments. As the poster said “They do not repeat information that you can read easily from the source code”. That removes most of the tendency for comments to get stale. Besides which, it doesn’t take much time to comment code as you write it, it just takes a little discipline which a developer needs to have. Comments prevent you from looking at you own code 6 months later and asking yourself….what was I thinking?
February 10th, 2008 at 3:18 pm
“Comments get out of date” is the rallying cry of people who don’t like to comment code in the first place!
People who take the time to comment code will/should also take the time to update those comments as/when necessary.
But of course, the extent to which this proves necessary depends to a large degree on the usefulness of the comment in the first place. A comment that is sensitive to small changes in code is probably not a useful comment in the first place and might be just as well removed as updated.
e.g.:
// Now we have finished with the query we can free it
FreeAndNIL(qry);
February 10th, 2008 at 3:27 pm
I 100% agree: There are very few cases when a comment is necessary. Every time I start writing a comment I stop to think whether it might not be a better idea to change the code in a way that makes it self explanatory, e.g. change the name of a function or parameter, change the type of a parameter e.g. from integer to an enum, refactor code to use “speaking” variable names for storing a part-result rather than having an unreadable monster formula etc. It is usually a better investment of the time to do this rather than writing a comment.
As you say - and as I have seen happening frequently - comments go stale because when changing the code very rarely the comments are adapted. And a wrong comment is even worse than none at all.
February 10th, 2008 at 4:13 pm
Sorry, but I never saw real-life code, that all programmers can understand quickly…
February 10th, 2008 at 9:25 pm
In essence I agree, most commenting is pretty useless and seems to be done just because the programmer was told they need to put in some comments. But the comments I care most about are not the one’s that could easily be gotten rid of with some intelligent variable and function naming (like the standard “this procedure does this” function header). The one’s that most concern me and that are most critical to me are those that describe changes made to work around an issue or fix a bug, particularly those that need to be made clear for the programmer coming afterwards (whether that’s me or someone after me). The second set of important comments are those noting what has been changed and why, when these changes are made to code in areas of a high level of concern.
February 11th, 2008 at 3:03 am
Descriptive method, variable and type names gets you a long way, but some times it is very useful to add a few comments that describe the goal of the code in question, clarify key events or decision points in a method, overall structure of a complex data model, or - in case variables are not self-explanatory - a little information about what you intend to store in the variable(s).
I try to avoid directly re-describing the algorithm, but instead try explain my goal. This puts some context around my sparsely commented code, and usually don’t get outdated by changes to the code. For primitives, it is important to comment the requirements for the in-data - at least if you don’t enforce those requirements with Asserts.
The “Real programmers don’t write comments - It was hard to write, it should be hard to read” model is passé. If the developer is to lazy to maintain his commentary, he probably writes sloppy code in the first place.
February 11th, 2008 at 11:55 am
Generally speaking, I tend to try to write code which is self-documenting in terms of what it does, and use comments to indicate why it does what it does.
February 11th, 2008 at 12:04 pm
“Generally speaking, I tend to try to write code which is self-documenting in terms of what it does, and use comments to indicate why it does what it does.”
That is the best advice here.
February 11th, 2008 at 6:25 pm
I agree with the practice of writing self-documenting code, but that only works so much. I’d challenge the best programmer to write self-documenting assembler. My amount of comments in C or assembler is drastically higher than my amount of comments in Ruby or OCaml.
My policy is to comment the reasons why I made decisions, not what the decisions are, but only if those reasons aren’t obvious. I don’t generally comment
free(foo), but I might if it’s not the usual usage. I try to simply comment my tricky code. Since I’m not writing code for teaching students, I trust that my reader has a basic fluency in both general programming and the language I’m using. If I’m (ab)using an advanced language feature, then I’ll comment.With my policy, comments are almost never stale, always helpful, and far and few between.
February 12th, 2008 at 8:06 am
[...] down methods into smaller pieces, extracting classes, and naming things well. When I posted about making comments less necessary, I figured there would be a lot of people who could benefit from that same knowledge, and tips on [...]
February 14th, 2008 at 12:05 am
[...] people disagreed when I said you should try to write code that doesn’t need comments. I’ll be addressing [...]
February 14th, 2008 at 5:41 am
There are several uses for comments even if you split your code/functions and name them and the variables “properly”:
1) ///<summary>Insert your function description here…</summary> before a function that Delphi picks up and shows you when you’re typing that function elsewhere;
2) { TODO : Something } that, again, Delphi picks up and lists in the ToDo list.
3) Documenting some hack: we all know we *shouldn’t* use them, but sometimes they get the job done JIT. Ideally couple that with a ToDo comment to rewrite that hack into clearer code later…
That’s pretty much everything I use comments for: when I opted for pascal vs. C++, I already was willing to type meaningful names. Heck, in my coding style, I rarely, if ever, use an IF *WITHOUT* using a begin/end pair and that’s even it it just has one instruction! I find it easier to visualize that there’s something there that will only be executed SOME times because I also couple that with proper indentation…