How to Write Comments

Denis Krukovsky writes "Should I write comments? What is a good comment? Is it possible to comment a class in 5 minutes? See " Everybody knows that good code is self documenting- which is why my prof in college demanded we write in Ada. I instead suggest commenting in haiku.

Comments

Good code is self documenting...

[Private Taco]

Just like good documents are self coding...

Re: Good code is self documenting...

[roman_mir]

First of all you are implying that people write good code. Secondly you are making a mistake thinking that all code is easy to read when it is good. This is a lie.

Obviously if you are writing some sort of a 3 tier application, which has a presentation, business and data tiers, then it is in fact possible to write good self documenting code, but you must also provide a design document, which explains how to read this code from high level point of view. But when you get into any specific details of that code or if the code is not a simply a goto database/do some formatting/print/get input from user/do some validation/write to database code, but something like: switch the coordinate system, do some trigonometry, create a complex data structure, display 3D world, then there is no way that code can be fully self documenting. Sure, a math genius may not require additional comments, but for everyone else, for people who are not that familiar with the domain of the problem at hand, comments are very important. Of an extremely detailed and very much up to date design document.

Re: Good code is self documenting...

[Canthros]

Good comments ought use good English. Punctuation, like apostrophes, and proper capitalization increases readability. Even if your spelling is impeccable, other grammatical niceties should be observed as well.

Even so, 'good code' is a combination of commenting and coding style. Probably, neither is sufficient alone. Even the most readable code will sometimes do things which are non-obvious or unintuitive, and comments, by themselves, cannot do near so much good as clearly, concisely, and well-styled code.

Re: Good code is self documenting...

[2short]

Self-documenting code is a wonderful thing, and greatly reduces the need for comments. Whenever someone brings this up, others say no, and eventually present an example such as yours: Entirely non-self-documenting. What the hell kind of variable names are those? L? a method named i()? Spell out "inverse" for gods sake! Of course you can't follow it. Hell, I know what Cholesky decomposition is, and I've read your explanation and I still don't know WTF that code is doing. I'll bet you needed 17 lines of comments. If you had instead changed the var names to something sufficiently descriptive, the code would successfully document what it is doing, leaving you to write a comment describing why; I suspect the third sentence of your post would have sufficed.

The why not the how

[Ckwop]

A comment should tell you why something is in place rather than what the code is doing:

A trival example:

Don't do this:

public bool CheckSmsValue(Account smsAccount)
{

// Check tarriff is null
if (Account.Tarrif == null)
          return;
...
}

Do do this:

public bool CheckSmsValue(Account smsAccount)
{

// 30-11-2005 Fixes a null reference exception that occurs later on if no reference is available.
if (Account.Tarrif == null)
          return;
...
}

Simon.

Re:The why not the how

[Malc]

Person pet peeve here: dates and names/initials on comments. That's what source control is for, so don't litter the code with them.

What I see here isn't preventing an exception, but rather checking the validity of a paremeter. I know it adds extra processing, but so many problems could be avoided if programmers put more effort in to input (e.g. parameter) validity checks. If it's an unusual situation, check for it in an assert as part of the pre-conditions at the beginning of the function (programming by contract). I'm assuming this is Java code in your example - does it not support assert now?

Comments tell reason.

[Daniel_Staal]

The code can tell me what it is doing, but it can't tell me what it is supposed to be doing. The comment should tell me why the code is doing what it is doing. Then I can look at the comment and code together and tell whether the code is right. (And the comment won't have to change as I modify the code: It either stays because the why still exists, or it is removed because it doesn't.)

Re:Haiku Commenting?

[mcvos]

When there aren't comments, it is hard to figure out what parts of what do which.

What parts do what should be clear from the names of function calls and variables, but whenever a function becomes longer than something really short, yes, it needs comments describing what happens where. If a function does something complicated, it's worth starting with a comment describing pre- and post conditions.

That said, before you add a comment, first check if you can make the various identifiers any clearer. And then still add the comment, unless it's suddenly become really stupid.

Comments First

[Doc Ruby]

Good comments are written first, before the code, describing what the following code does. It is gramatically correct, punctuated, easy for a stranger to read. It says what the following code does in terms of the real world, not just in terms of other code, unless the sole purpose of the code is to connect other code without relation to anything expressible in real world terms. I prefer my comments to be in the present tense, as if they could be directly compiled themselves. I put comments inside practically every block, like function definitions, loops, conditionals. I often put comment labels after block closers, especially complex conditional sets, embedded loops and functions. That labeling makes it easier to keep track of context within which variables, their scope and the "current task" are in operation. I'd rather spend a few more seconds typing up front, and save a lot of scrolling and delimiter-matching later (not to mention reducing confusion and mistakes).

Code gets shuffled around in different order, read by strangers, and reread much later by yourself, often after you've changed by experience (either in programming or in the task being programmed). Writing the code first is a good way to outline the program, and to detect flaws in your approach. It also gets a little bit of the program done, on screen where you can see it. Often coding to support the comments is more like a cleanup task than starting from scratch.

Re: Comments First

[Black Parrot]

> Good comments are written first, before the code

When implementing a big program or non-trivial algorithm, I start the file with comments that end up serving as an outline for the code I insert afterward. It helps clarify my thoughts about how I'm going to go about it, and of course keeps me from forgetting anything.

Re:Comments First

[Doc Ruby]

The design is usually in different terms than the code. When intelligible, the design that accompanies the code would make good comments. But often the design is at a different level of abstraction, or in terms of entities not directly represented in the code, or omits important artifacts of the code or the machine itself. A good project has design documentation, code comments, and code, all referencing each other, each understandable in its own terms (the code by both humans and machines). And of course all maintained in sync with the other, which they all reference.

The need for each of those work products by different people/machines at different parts of the project cycle is one reason I've been waiting for flowchart programming for many years. When we can flip between lexical and graphical representations of the same executable, with attached multimedia documentation, we'll have much more efficient team understanding of the code. Object techniques have brought us a lot closer, but we still have a lot of skills (topological sense, geometrical arrangement) that we can use to work better to make the machines do what we want, not just what we asked for.

Re:Comments First

[Henrik S. Hansen]

Good comments are written first, before the code, describing what the following code does.

That's some of the worst advice I have seen wrt. code commenting. Comments should never describe what the code does. If it is not obvious from the code, it should be refactored.

The strategy of verbose and essentially redundant comments are bound to end up in outdated and/or useless comments. If such a practice is employed in industry, forcing people to comment every loop, etc. as you describe, I'm certain there would be a lot of useless comments.

People will simply not do something, which they cannot see how they would later benefit from. Classic CSCW problem.

Re:Comments First

[booch]

Comments should never describe what the code does.

It seems that most folks here believe that -- that you should only comment on why you're doing things, not what you're doing. But I think that's a bad idea. For example, let's say you've got some "code" that says:

Combine an egg, some flour, some milk, some sugar, ...

I would contend that the comment should be "make a cake". I suppose you could contend that tells why we're combining the ingredients, but I think it's more clear to say that that is what we're doing. My point is that what we're doing is not at all obvious from just looking at how we did it.

Re:Haiku Commenting?

[PsychicX]

Possibly the best advice I ever read/heard (I can't remember the origin), is to assume that the guy reading your code is perfectly familiar with the language. (Sadly this is usually inaccurate, but moving on.) So he can see what, mechanically, your code is doing. The idea of a comment is to explain how and why you are doing something. What is usually clear from the function name and accompanying documentation (be it doxygen/javadoc style or MSDN style or something else). I.e. if you have some jacked up mega-compound for-loop, a good comment explains why that loop is the way it is, and how it's achieving its goal (and possibly what precisely it's doing). A bad comment would be "this loop increments i, j, k, theta, and cheez_it until the cheez_it is failing to exceed the sum of i, j and the product of i, j, and k". That kind of information is right there in the code.

In short, comments convey concepts and explanations, not mechanical descriptions.

Re:Check out Rob Pike's thoughts on code commentin

[squiggleslash]

I'm not sure I do.

He's used two stupid examples of commenting, examples that are popular jokes, rarely appearing in real life and usually the result of sarcastic nudge-nudging from experienced programmers, and pretended that's what we're talking about when we talk about commenting. When he finally admits they may have a use, the description is so vague it's hard to see what he means - which, if he comments the same way, is probably as true of his code as it is his prose.

It doesn't take much, or add any clutter to code, to put a brief, one or two line, comment before each paragraph of code, that describes the intended functionality of the code block. It makes a massive difference when you revisit your code three years, or even three months, later, or worse have a collegue look at it.

Nor is it a massive imposition to have more obscure decisions you've made be explained in a comment block before the code itself.

Code is not self-documenting. It becomes intensely verbose when you try to make it self-documenting, and it's rare that anyone, no matter how well skilled, can produce something that transmits the intended functionality of the written code in the implemented functionality. This is especially true if you're using an optimal algorithm. Reasonable, non-excessive, use of comments, describing functionality rather than function, are extremely important.

Re:Comment every conditional branch or loop

[MemeRot]

Comments can be good,
Avoid 'magic numbers' too,
You've heard of constants?

Seriously, this is not good code: if (u & 0xFF1234) - what the hell is u? Is it the start of the file? What if your file structure changes, you want to grep for every instance of 0xFF1234 and see if it needs to be changed? What if you changed your definition of what a good file is?

Why not: if isValid(fileStart) - or if all you're doing is printing, just put it in the print statment? You do have to comment to explain why you're doing something, but the clearer the code is the easier it is to read and maintain.

Re:Check out Rob Pike's thoughts on code commentin

[prgrmr]

"Procedure names should reflect what they do; function names should reflect what they return"

This is one of the most effective methods of producing self-commenting code and I wish everyone writing programs would do this.

Re:Haiku Commenting?

[Rorschach1]

I'd suggest an exception to this for embedded code. When I'm writing something for a PC, sure, there's no excuse for not making the code readable. But when you're squeezing as much functionality as possible into a chip with maybe a couple hundred bytes of RAM and a few KB of flash, things get ugly.

It's not uncommon for my code to do something really non-obvious to accomplish a task in a more efficient way. Processing sensor readings, for example - on a PC it'd be a simple floating point math operation. On the chips I use, the floating point library would itself fill the entire available memory. Instead, I wind up with a bit of hard-to-read code that accomplishes the same thing using the shift and multiply operations the CPU is good at. For my own sanity I leave very specific comments about what's going on and what the equivalent calculation is.

'Why', not 'How'

[lawpoop]

The code is the 'How'. What the reader needs to know is 'Why' you are taking these steps. What larger goal are you accomplishing? What is the purpose of this code? What is its justification for existance?

Fill in this blank: "If were weren't running this code right here right now, we wouldn't be able to do _____. We could have done it this other way, but we chose this method because of X, Y, and Z.

In a real world example, code is like "Turn left, Go to High Street, turn right, continue on to 1122 High St, pull into the driveway, and park the vehicle." Those are the steps taken, but the goal you are acommplishing is "We want to return the library books, so we are going to drive the books to the library using the car."

OK, so why are we taking the books to the library? Ultimately all comments will filter up to the goals of the application. They are all nested subgoals of the design specs.

Comments are Critical to larger scale projects

[localman]

Sure, well written code should read clearly and be clear about what is happening at every step. But in any larger scale project, no matter how well you make your data structures or how cleanly you encapsulate, eventually you'll code things where the motivation isn't clear.

Good comments don't talk about the code itself, they talk about why the code is doing what it's doing. What the code is doing should be obvious if it's well written, but I've never written a code file that couldn't benefit from a little english exposition.

Cheers.

"should I write comments?"

[tomstdenis]

Boom, you're fired.  If you have to ask that you're clearly incompetent.

As to what a good comment is, it's something that gives context to a section of code.  Comments aren't supposed to "explain" every step of an algorithm but rather explain why they're there...

e.g.

// for loop from 1 to 5
for (i = 0; i < 5; i++)
   // strcmp for "key"
   if (!strcmp(strings[i], "key")) dowork();

Could be written better as

// we are going to look for the string "key" in the array
for (i = 0; i < 5; i++)
   if (!strcmp(strings[i], "keys")) dowork();

(better yet is to replace '5' with some constant or other label).

In cryptographic tasks I assume the reader has the RFC [or other spec] handy and I just explain what parts of the standard I'm fulfilling, e.g.

// step 3c, xor key with 0x5e
for (i = 0; i < keylen; i++) key[i] ^= 0x5e

That way the reader can follow my code against the spec quicker.

If you're not capable of these sorts of comments it's because you don't think like a developer.  You're slinging one line of code against another instead of properly breaking your task down into many smaller more modular tasks which can then be easily expressed on their own.

Tom

lazy programmers

[MatD]

People use the 'code should be self documenting' excuse because they are lazy and don't want to take the time to actually write documentation.

If you are programming anything non-trivial, you are going to have sections of code that are obscure, and when you have to go back and fix a bug, or add functionality, you won't have any idea what the hell you were doing.

For example, I've written code that had to run on displays with 256 color palettes in windows. It involved saving the current palette when the window gained focus, and then restoring it when the window lost focus. But I couldn't even tell you how I did that now. If I had to go back and look at that code today, I'd have no idea what I was thinking. I do recall that is wasn't actually very many lines of code.

Back before UML was a common thing, I used to 'write' my code in comments and stubs, as a design. After I could read through the code as a narrative of what my app/service/dll did, I would actually fill in the stubs to make it work. This ended up saving me a lot of time in the long run, as I didn't really have much refactoring work to do while coding.

Re:Comments Not Needed...

[bmalia]

"Good code" will be easy to read AND have good comments. For example, my company has some old SQL Reports that need to be maintained on rare occasion. I can kind-of-sort-a make out what the code is doing, but I am not used to that syntax and I havn't been able to find any tutorials for the stuff on the web anywhere. It sure is nice to have comments along with the code that I can read in english what the code is doing. "This will print the subtotals","This pulls the exchange rate", etc. Does that make it a bad programming language? Probably, but it still has to be maintained. Life sure would be alot more difficult for me if the original programmer of those old reports had thought that comments were a waste of his time.

Re:Reading

[IngramJames]

an distract from actual comprehension of what is going on while reading the code, particularly when there are bits of orphaned antique leftover comments

I know this is a religous topic, but I personally would say that old, left-over comments are simply bad practice. Well-maintained comments and well maintained code are the ideal solution. I don't think there's any excuse for not updating a comment which is right there, in the code you're about to change.

I've suffered from antique comments, and also no comments; IMHO, they are both as bad.

Feel free to flame me now :)

Re:Comment every conditional branch or loop

[2short]

What a great example of lousty code and worse comments. How about the folowing... (Slashdot appears to offer a couple different ways to mis-format code; I've chosen incorrect indenting over comments can't start a line)

// the only thing a comment here should explain is why you use & and not ==
if (uFileHeader & VALID_FILE_HEADER)
{
printf("File shares at least one set bit with a valid file!\n");
}
else
{
// reason "blah, blah, blah", which I can not imagine existing,
// certainly deserves a comment, but it applies to the decision
// to say (falsely) "file not found", so it belongs here.
printf("File not found.\n");
}

Re:Reading

[ebh]

Code should tell you what
And the code should tell you how
Comment tells you why

Article Author on Crack

[dmatos]

As per the subject line, the author of this article is on crack. I'm not going to argue the why's and wherefores of his text, but I have a major objection to his "when". He states that the best time to comment code is once it's all done, and you're just about to submit it. WRONG!

Has he ever worked on a major project? One that cannot be held in one brain in its entirety at one point in time? START with the comments. Start with the program architecture. Decide what each part will do. Write out how each part will accomplish its goals. Then, copy/paste that into your editor, and write the code to match the comments.

Believe me, if you can plan out how everything will work in the first place, and then just follow your plan, the whole project will be much easier. An added bonus is that the code comments just come straight from your design document. Of course, from the tone of the article, I'd guess that this guy's response would be "What design document?"

Re:Haiku Commenting?

[Drachemorder]

That's probably useful advice in a general sense, but I can envision examples where commenting a single line might be useful. Consider the case of a complex regular expression: not everyone can glance at one of those monsters and immediately understand exactly what it does. A comment explaining what the thing does and why would be useful to most folks.

Question for all the coders out there..

[TiggertheMad]

I am an old school coder, and I see a lot of this stuff these days:

if (foo) {
// Bleah
// Bleah
// Bleah
// Bleah
}


Why do people put the opening bracket on the same line as the conditional? where the hell did this come from? I see it a lot in JS, and more modern C/C++ code. I always though you were supposed to use carrage returns and tabs to make it easy to see the body of a conditional:
(underscores for whitespace; damn you slashcode!)

if (foo)
{
_____ // Bleah
_____ // Bleah
_____ // Bleah
_____ // Bleah
}


Did I miss something? Are all the 'cool' coders doing this now, and I'm just old?

Re:Question for all the coders out there..

[aaza]

Believe it or not, one place it comes from is presentation slides (PowerPoint, or just plain overhead transparencies).
It lets you get the whole example on the page in a font that is readable from the back of the lecture hall.

Personally, I prefer it like this. The opening brace on the line with the conditional (for, while, if, etc), the conditional block indented, and the close-brace at the same indent as the start of the conditional. I tried a few other ways*, but didn't like them: they weren't readable enough for me.

* Other ways tried:
Open and close brace on separate lines to condition, at the same indent, code indented further (which you have above)
Braces and code indented further than the conditional, but lined up with each other
Braces indented from conditional (lined up with each other), code indented from braces [this was the worst]

It's largely a matter of personal choice, or project code rules, really.

Re:Question for all the coders out there..

[Chemisor]

> I am an old school coder
> Why do people put the opening bracket on the same line as the conditional?

You must not be very "old school" if you don't know the answer. The cuddled braces are the original K&R indentation style; they are what C was supposed to look like.

Another answer is that there are two different ways to look for blocks. I look at indentation as a clue to the new block and when I see a brace on a line by itself I immediately interpret it as:

if (x);
{
}

This is especially true when I can't see the end of the line. Obviously, it doesn't take long to switch mental gears, but it is inconvenient. No, I am not going to switch to this style. You have to indent the code anyway and since the indentation change already says "new block", the brace is redundant, and therefore should not be emphasized. I might also point out that the braces are only required for multiline blocks anyway, so looking for indentations is a skill every C programmer needs, wherever he places the braces.

People who put braces on separate lines look for the opening brace itself to signal the start of the block and panic when they see indentation level change without it. It is really just another way of looking for blocks, and I am disappointed that it is so commonly taught.

Re:Question for all the coders out there..

[jallen02]

I started coding doing K&R C style braces. I have used them for many many years. I have recently been trying the opening brace on a separate line. It isn't so bad. There are a LOT of languages out there other than C. You can make a bunch of logical arguments for both ways. It is almost like vi vs. emacs. I can spot blocks either way. I also do a lot of Ruby coding which doesn't even use braces and instead uses the end statement to denote the end of the block. So you actualyl *have* to know what statements can start a block to even begin to know if you should be looking for an end to the block.

As long as you are consistent with your style others will be able to read your code. Maintainability matters more than stylistic preference and both styles are maintainable. They are called STYLES after all.

And technically automatically interpreting a line without a brace as a terminated statement (IE: with the semicolon) can be just as bad as programmers that can't find a block of code. You should know the language well enough that you can interpret any common brace style. Ok.. no more nit picking.

I think one of the reasons it still dominates is it still gets used in book writing to condense lines of code. Almost all developers read code examples written here and there. I think this is big on continuing the tradition. When I was working on a my PHP book I know I used the brace on same line as the conditional method because it saved lines.

In the end being consistent trumps stylistic preference. The best argument I have seen is for condensing code. It does save a line or two here and there if you really need it. With 1280x1024 being a relatively common display resolution used by developers these days I don't think it is such a big deal to have an extra line for the braces :-)

Jeremy

Re:Are you reading the same thing I am?

[petermgreen]

basic programming classes seem to push overcommenting.

good comments should imo cover
1: the why (why am i doing it this way)
2: the why not (why am i not doing this the obvious way)
3: the high level what (though to some extent this can be pointed out through method signatures etc)
4: the low level what in cases where it wouldn't be obvious to someone reasonablly skilled in the language.

However you don't get many of those in trivial programming excercises but the teachers are still supposed to encourage people to use comments. So naturally comments that point out trivialites are the result.

Hard problems

[Dire Bonobo]

> If it is not obvious from the code, it should be refactored.

If it is obvious from the code, your project is too simple.

(Flippant, but not totally false. I work on research code that does...significantly complicated things. It can be hard enough for me to keep track of the interactions of the algorithms even when I'm designing them on paper; translate them into code, and the result is not at all trivial.

What my code does can be hard to understand when I've made a serious effort to clearly explain what it does in prose; even then, I expect understanding what it's doing to require effort from other researchers in my subfield. To expect any of them---much less a more junior researcher---to understand what is going on from the code alone is simply nonsensical. They would dismiss it as a waste of their time, and rightly so.

If code were that easy to read and understand, it would be found in most computer science research papers; that such papers avoid it like the plague suggests that's not the case, even for less-complicated problems.)