How to Write Comments 556
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.
Good code is self documenting... (Score:5, Insightful)
Ada Rocks (Score:1, Insightful)
Denis who? (Score:1, Insightful)
I did RTFA: it was poorly written and makes some statements that most people would STRONGLY disagree with. For instance:
The point to start writing comments is... when the code is ready to be presented for others.
The why not the how (Score:5, Insightful)
A trival example:
Don't do this:
public bool CheckSmsValue(Account smsAccount)
{
if (Account.Tarrif == null)
return;
}
Do do this:
public bool CheckSmsValue(Account smsAccount)
{
if (Account.Tarrif == null)
return;
}
Simon.
Comments tell reason. (Score:5, Insightful)
Re:Haiku Commenting? (Score:4, Insightful)
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 (Score:5, Insightful)
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:Haiku Commenting? (Score:5, Insightful)
In short, comments convey concepts and explanations, not mechanical descriptions.
Re: Comments First (Score:5, Insightful)
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.
Comment removed (Score:5, Insightful)
Re:Comment every conditional branch or loop (Score:5, Insightful)
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 (Score:3, Insightful)
This is one of the most effective methods of producing self-commenting code and I wish everyone writing programs would do this.
good code is not self-documenting (Score:0, Insightful)
As the OP says, code will only ever tell you the "how" not the "why". As in this snippet:
i++ ; increment counter
while trivial, it tells you nothing about why you wish to increment the counter. Ada,C(++) or any other high-level language is always limited to this.
The best comments are a summary at the start of a block of code that describes the autors intent. It should have correct spelling and grammar. if the coder can't even get the coment right - the code is probably wrong, too.
Re:Haiku Commenting? (Score:5, Insightful)
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.
Re: Good code is self documenting... (Score:3, Insightful)
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:The why not the how (Score:4, Insightful)
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?
'Why', not 'How' (Score:5, Insightful)
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.
Re:Haiku Commenting? (Score:2, Insightful)
I've always thought that you should be able to tell what is happening from the code... the comments are supoosed to tell you *why* it's doing what it's doing.
Re: Good code is self documenting... (Score:3, Insightful)
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.
Comments are Critical to larger scale projects (Score:4, Insightful)
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?" (Score:3, Insightful)
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
Re:Comments First (Score:3, Insightful)
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.
lazy programmers (Score:5, Insightful)
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... (Score:2, Insightful)
Ah, the age old programming question (Score:1, Insightful)
I mean, any reasonably skilled programmer should be able to look at a block of code and understand what is going on without an excessive description of what the original programmer intended to do. But there are always those cases, especially if the original programmer got crafty and found ways to streamline or optimize the code for performance, where anybody not involved in the original development would just scratch their head and wonder what the heck is going on.
Comments can be very detrimental in many cases. If I get some code that is heavily commented, to the point where the actual code is separated by long blocks of commented code, I just nuke the comments and condense the file. I have actually found files that are thousands of lines long be reduced to only a few hundred lines be removing superfluous comments, and the actual code is easier to understand without the unecessary comments.
NOBODY should ever write a comment like
int x = 5;
I mean, this is a very obvious and exagerated case, but often this happens. It is very obvious what the code is doing, anyone with at least 1 day of programming lessons can understand it easily.
Usually, its more like
bool y = false;
Why should y be initialized to false. I many cases, false is just an arbritrary initial value, but in some cases, the initial condition is important, this importance should be commented and highlighted.
For the most part, comments end up being inaccurate.
double Z = 6.1;
So what do you do here? If your reviewing the code, is 10.2 still the important value, or has a bug been fixed by changing the inital value to 6.1. Is a bug occuring because Z is not 10.2?
As a programmer, one should never blindly read the comments and not review the code. Learning to understand the code makes more sense then deciphering the comments. In most cases, the comments are either superfluous, meaningless, or just wrong. The best skill a programmer can learn is to ignore comments and read the code.
Ultimatly, I comment a block of code to give a general sense of what I am trying to do. I don't go into particulars within a section such as why I am deleting a pointer or loading a value (it should be obvioius what your doing), its the end result that is important, not all the minutia involved in getting there.
Also, I CAN'T stand notation that lists the history of file changes. I mean, the CURRENT code is what your interested in, not what someone did 6 years ago. Knowing that person X modified Line Y in 1992 is of no benefit to my ability to read, understand, fix, or update code in 2005. Often, these modifications refer to code changes that no longer exist in the file. Someone made a fix to code in 2001, but someone in 2003 rewrote the whole code, the 2001 fix is irrelavent. Serious programmers invest in a source control product, like Visual Source Safe, CVS, or SubVersion. These programs STORE the history of a file, there is no need to write a header that can be hundreds of lines long telling you about all the bug fixes and file changes. If you need to review old code, simply go into your source control and compare the file between 2005 and 1992 to find out what is different and changed. Often, most of the people involved in the file's history no longer work at the company.
Lastely, one of the MOST important commenting tricks is to insert nothing at all! A blank line can speak volumes. It can separate functional sections in code, allowing you to understand the flow of the code and realize when certain results are accomplished. I am an object oriented programmer, so seeing blocks of functional units where a blank line separates some operation or result just makes sense (even more if you turn the code section into a class
This rubbish again (Score:1, Insightful)
Sigh. This rubbish again. That a lecturer is promoting this nonesense is even worse.
The "self documentation" you refer to means that you cannot check the documents against the code in order to detect errors. It also means you cannot check the tests against the documents to detect errors - you can only check the tests against the code, which is self defeating.
Good code is commented. The best code in the world that has no comments is
a maintenance nightmare - how can you tell why a particular part of the code
is written this way rather than that way and why is that special case there?
Those that don't believe this either haven't been writing software long enough or have yet to work on a sufficiently large and complex product to
realise the error of their ways.
I'm currently working on a project that is 11,000,000 lines of C++ and assembly including comments. About 7,000,000 without comments and without whitespace. It would be a nightmare without the comments (i.e. "self documenting" - pah).
Re:Reading (Score:5, Insightful)
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 (Score:3, Insightful)
// 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
{
printf("File not found.\n");
}
Re:Haiku Commenting? (Score:1, Insightful)
One nice thing about doing it this way is that I don't usually need to re-write my comments even if I change my implementation (unless my original comments weren't abstract enough). A downfall is that someone hunting down a bug in my code might rely too much on my comments and not see the bug. But then again, at least the maintenance programmer will know what I was thinking and what I was trying to accomplish, and will hopefully have a better idea of how to fix it.
I guess my brain just works best if I write the comments first, rather than last. It helps me keep my focus and see the bigger picture as I go...
Re:Reading (Score:5, Insightful)
And the code should tell you how
Comment tells you why
Article Author on Crack (Score:5, Insightful)
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:Comments First (Score:5, Insightful)
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:Haiku Commenting? (Score:3, Insightful)
Re: Good code is self documenting... (Score:5, Insightful)
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.
Question for all the coders out there.. (Score:3, Insightful)
if (foo) {
}
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)
{
_____
_____
_____
_____
}
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.. (Score:3, Insightful)
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:Comments First (Score:3, Insightful)
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:
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:Question for all the coders out there.. (Score:3, Insightful)
> 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:Are you reading the same thing I am? (Score:3, Insightful)
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.
Re:Question for all the coders out there.. (Score:3, Insightful)
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
Hard problems (Score:3, Insightful)
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.)