Comments on: Making comments less necessary

By: Fernando Madruga

Fernando Madruga — Thu, 14 Feb 2008 11:41:45 +0000

There are several uses for comments even if you split your code/functions and name them and the variables “properly”:

1) ///

Insert your function description here…

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…

By: Joe White’s Blog » Blog Archive » If it’s important enough to comment, it’s important enough to test

Thu, 14 Feb 2008 06:05:54 +0000

[...] people disagreed when I said you should try to write code that doesn’t need comments. I’ll be addressing [...]

By: Joe White’s Blog » Blog Archive » Making comments less necessary, part 2

Tue, 12 Feb 2008 14:06:20 +0000

[...] 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 [...]

By: Samuel Tesla

Samuel Tesla — Tue, 12 Feb 2008 00:25:33 +0000

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.

By: Chris

Chris — Mon, 11 Feb 2008 18:04:12 +0000

“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.

By: Craig Stuntz

Craig Stuntz — Mon, 11 Feb 2008 17:55:04 +0000

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.

By: Lars Fosdal

Lars Fosdal — Mon, 11 Feb 2008 09:03:25 +0000

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.

By: Andrew V.

Andrew V. — Mon, 11 Feb 2008 03:25:35 +0000

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.

By: Lars D

Lars D — Sun, 10 Feb 2008 22:13:05 +0000

Sorry, but I never saw real-life code, that all programmers can understand quickly…

By: Thomas Mueller

Thomas Mueller — Sun, 10 Feb 2008 21:27:12 +0000

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.