Comments on: No Comment I thoroughly agree with the "Comments must say why, not how" part. But does that remove all comments? Not by a long shot. Most programmers I've worked with are amazingly good at thinking the "why" is obvious, when a short time later, it isn't even to themselves any longer. I'd say comment the "why" liberally, <em>especially</em> when it seems obvious. I thoroughly agree with the “Comments must say why, not how” part.

But does that remove all comments? Not by a long shot.

Most programmers I’ve worked with are amazingly good at thinking the “why” is obvious, when a short time later, it isn’t even to themselves any longer. I’d say comment the “why” liberally, especially when it seems obvious.

]]>
By: expartend/2011/03/28/no-comment/#comment-2114 expartend Tue, 29 Mar 2011 11:25:37 +0000 If the code mismatches the comment, that doesn't mean the comment is bad. Rather than seeing them as a burden in maintenance, comments can help prevent and correct <i>bad code</i>. They're even useful for documenting cases while I'm writing the code the first time. Going further than what MarcT pointed out: if you're adding a new method to explain code, then it's hard to justify possibly messing with the binary output and adding even more code to have what is essentially a string of text on a single line of your code file. A method might help the code in other ways. However, does the extra method fracture logically grouped code? It may be harder to keep several of these related methods up to date during a maintenance pass. It also might increase branching overhead for each obscure special case you attempt to turn into a method, even if it's inlined. If the code mismatches the comment, that doesn’t mean the comment is bad. Rather than seeing them as a burden in maintenance, comments can help prevent and correct bad code.

They’re even useful for documenting cases while I’m writing the code the first time.

Going further than what MarcT pointed out: if you’re adding a new method to explain code, then it’s hard to justify possibly messing with the binary output and adding even more code to have what is essentially a string of text on a single line of your code file.

A method might help the code in other ways. However, does the extra method fracture logically grouped code? It may be harder to keep several of these related methods up to date during a maintenance pass. It also might increase branching overhead for each obscure special case you attempt to turn into a method, even if it’s inlined.

]]>
By: Dylan Cuthbert/2011/03/28/no-comment/#comment-2107 Dylan Cuthbert Tue, 29 Mar 2011 03:35:26 +0000 <blockquote>Whenever you feel the need to write a comment, write a method instead</blockquote> And how do you deal with the icache?

Whenever you feel the need to write a comment, write a method instead

And how do you deal with the icache?

]]>
By: Reddog/2011/03/28/no-comment/#comment-2100 Reddog Mon, 28 Mar 2011 22:08:58 +0000 I actually agree with you in that all my comments say is already said in the code (btw the code is from a real project of mine). But that was exactly my point. The comments being english instead of C are more convenient to scan the code quickly. Also they "stand out", especially with code highlighting which should be quite standard. My reason to use seemingly redundant comments is that I save time when I read a function which is structured in blocks with a short comment stating what the block is doing. Even if the block is as short as writing out a resulting pointer. This way I just have to read the green lines and get a quite good idea of what's happening there. Also, as I mentioned above, I don't like to introduce functions just to encapsulate 5 lines of code which will be used once anyway. That might be inlined by the compiler, but to be honest I'd rather "inline" it myself and give it a short comment. As long as it doesn't result in a giant function body I think it's even better than calling a function like instantiateParser(), because you see the actual code (as you stated in the article). I think that's similar to how one structures a long article in sections with a headline. At least for me it's very convenient to read code like this. I actually agree with you in that all my comments say is already said in the code (btw the code is from a real project of mine).
But that was exactly my point. The comments being english instead of C are more convenient to scan the code quickly. Also they “stand out”, especially with code highlighting which should be quite standard.

My reason to use seemingly redundant comments is that I save time when I read a function which is structured in blocks with a short comment stating what the block is doing. Even if the block is as short as writing out a resulting pointer. This way I just have to read the green lines and get a quite good idea of what’s happening there.

Also, as I mentioned above, I don’t like to introduce functions just to encapsulate 5 lines of code which will be used once anyway. That might be inlined by the compiler, but to be honest I’d rather “inline” it myself and give it a short comment. As long as it doesn’t result in a giant function body I think it’s even better than calling a function like instantiateParser(), because you see the actual code (as you stated in the article).

I think that’s similar to how one structures a long article in sections with a headline. At least for me it’s very convenient to read code like this.

]]>
By: Francesco Carucci /2011/03/28/no-comment/#comment-2097 Francesco Carucci  Mon, 28 Mar 2011 21:03:08 +0000 If you haven’t read Steve Yegge’s Portrait of a N00b, I highly recommend it (along with most everything else he’s written).

I agree with Aurelien in Comment #1 – the code tells me how, and usually why if the method names are good. But sometimes writing a “GuardAgainstSpuriousNotificationEventsOnSB16Cards()” function is better expressed with a single-line if statement and a comment.

]]>
By: Justin/2011/03/28/no-comment/#comment-2091 Justin Mon, 28 Mar 2011 19:42:21 +0000 It's amazing how such a topic can spawn a giant discussion. My two cents: I normally use comments to divide a longer function into blocks. Like this: <code> CC_ParserResult CC_Parser_Create(CC_Parser** outParser, char* text, uint32_t textSize) { // local vars CC_Parser* parser; CC_ScannerResult res; // instantiate the parser object parser = INSTANCE_MALLOC(CC_Parser); parser->mText = text; parser->mTextSize = textSize; parser->mMessageString = ARRAY_MALLOC(char, CC_PARSER_MESSAGE_STRING_LENGTH); parser->mStringBuffer = ARRAY_MALLOC(char, CC_PARSER_STRING_BUFFER_LENGTH); // create a scanner object for the parser res = CC_CreateScanner(&parser->mScanner, parser->mText, parser->mTextSize); if (res != CC_SCANNER_OK) { return CC_PARSER_SCANNER_CREATION_FAILED; } // write the resulting parser pointer *outParser = parser; return CC_PARSER_OK; } </code> Now some could argue I should instead write a function AllocParser() and maybe just drop the first and the last two comments. But if I just keep these comments I can spot at a glance that my function is divided into 4 logical blocks and what they roughly do by just looking at those happy little green comment lines in VS. Also normally I prefer not to write another function (like AllocParser) if I'm only gonna use the code in one place. If I need to separate this code into an own function later, that's 5 mins of work. For me this works best and to be honest I can't imagine why other programmers would get offended by this style. Sorry for the bad code-formatting, I couldn't find a way to indent properly :( It’s amazing how such a topic can spawn a giant discussion. My two cents:

I normally use comments to divide a longer function into blocks. Like this:

CC_ParserResult CC_Parser_Create(CC_Parser** outParser, char* text, uint32_t textSize) {
// local vars
CC_Parser* parser;
CC_ScannerResult res;

// instantiate the parser object
parser = INSTANCE_MALLOC(CC_Parser);
parser->mText = text;
parser->mTextSize = textSize;
parser->mMessageString = ARRAY_MALLOC(char, CC_PARSER_MESSAGE_STRING_LENGTH);
parser->mStringBuffer = ARRAY_MALLOC(char, CC_PARSER_STRING_BUFFER_LENGTH);

// create a scanner object for the parser
res = CC_CreateScanner(&parser->mScanner, parser->mText, parser->mTextSize);
if (res != CC_SCANNER_OK) {
return CC_PARSER_SCANNER_CREATION_FAILED;
}

// write the resulting parser pointer
*outParser = parser;

return CC_PARSER_OK;
}

Now some could argue I should instead write a function AllocParser() and maybe just drop the first and the last two comments. But if I just keep these comments I can spot at a glance that my function is divided into 4 logical blocks and what they roughly do by just looking at those happy little green comment lines in VS. Also normally I prefer not to write another function (like AllocParser) if I’m only gonna use the code in one place. If I need to separate this code into an own function later, that’s 5 mins of work.
For me this works best and to be honest I can’t imagine why other programmers would get offended by this style.

Sorry for the bad code-formatting, I couldn’t find a way to indent properly :(

]]>
By: Tiziano Sardone/2011/03/28/no-comment/#comment-2085 Tiziano Sardone Mon, 28 Mar 2011 18:03:33 +0000 I doubt that they would appreciate having to work with code that is damaged by comments. Many middleware developers add external documentation in the form of a HTML Help file and it seems to be working quite well. If it's all about trying to look good in the eyes of a customer (instead of making quality middleware), I doubt that it's going to solve anything. Middleware users aren't fools, they're also programmers. And I believe that they, just like most people here, would appreciate having proper documentation where it belongs, where it can be browsed/searched, where it doesn't get in the way of programming.   If you think that heavy amounts of comments are useful for the code, then I // trying to make this a bit more personal hope // inability to enforce this makes me simply want for this to happen that // for compatibility with different "compilers" you // trying to make this even more personal to make my point can // a shortened version of different phrases that could be used instead read // this action is required by the function to parse it properly this // points to the current object . // finishes the sentence and stops parsing, moves to the understanding phase   Might be a bit too much to make my point but I've seen even worse comments on some APIs. :D I doubt that they would appreciate having to work with code that is damaged by comments. Many middleware developers add external documentation in the form of a HTML Help file and it seems to be working quite well.
If it’s all about trying to look good in the eyes of a customer (instead of making quality middleware), I doubt that it’s going to solve anything. Middleware users aren’t fools, they’re also programmers. And I believe that they, just like most people here, would appreciate having proper documentation where it belongs, where it can be browsed/searched, where it doesn’t get in the way of programming.
 
If you think that heavy amounts of comments are useful for the code, then
I // trying to make this a bit more personal
hope // inability to enforce this makes me simply want for this to happen
that // for compatibility with different “compilers”
you // trying to make this even more personal to make my point
can // a shortened version of different phrases that could be used instead
read // this action is required by the function to parse it properly
this // points to the current object
. // finishes the sentence and stops parsing, moves to the understanding phase
 
Might be a bit too much to make my point but I’ve seen even worse comments on some APIs. :D

]]>
By: Peter Christensen/2011/03/28/no-comment/#comment-2081 Peter Christensen Mon, 28 Mar 2011 17:08:08 +0000 There is a code style that eschews comments in all but the most dire cases. Robert C. Martin argues for that style in his book Clean Code. I dislike it because all the refactored functions look like they're ready to be called from anywhere even if they are only intended to be called from one place. You can use asserts to add context, but it would be better to not have this problem at all. I completely agree that if you can solve the problem with a better design, commenting is not desirable. But that only applies when the design is <strong>overall</strong> better, not just better in one way. I don't understand people complaining about comments because they can get out-of-date. Yes, comments can rot, but so can every other thing that is not running code. Comments require maintenance and ongoing effort; you don't get something for nothing. I like them because I can edit them without switching away from my IDE or opening a different file. If you can't keep comments current, I wouldn't necessarily trust any other form of documentation you make. There is a code style that eschews comments in all but the most dire cases. Robert C. Martin argues for that style in his book Clean Code. I dislike it because all the refactored functions look like they’re ready to be called from anywhere even if they are only intended to be called from one place. You can use asserts to add context, but it would be better to not have this problem at all.
I completely agree that if you can solve the problem with a better design, commenting is not desirable. But that only applies when the design is overall better, not just better in one way.
I don’t understand people complaining about comments because they can get out-of-date. Yes, comments can rot, but so can every other thing that is not running code. Comments require maintenance and ongoing effort; you don’t get something for nothing. I like them because I can edit them without switching away from my IDE or opening a different file. If you can’t keep comments current, I wouldn’t necessarily trust any other form of documentation you make.

]]>
By: snake5/2011/03/28/no-comment/#comment-2079 snake5 Mon, 28 Mar 2011 16:10:41 +0000 Attempting to define the perfect policy on comments is a no-win situation.  Some people want a lot, others want little to none.  Everyone has a different workflow and is expecting different things.  For those of you trying to sell a middle-ware product your preference is largely irrelevant, or should be. <b>What do your customers want?</b> Do they want heavy amounts of API and line documentation?  Code that's easy to read? A lot of system documentation?  The answer to all of these is going to likely be Yes if you ask them. You certainly shouldn't ask people a trick question about their preference about comments.  I don't have the right answer when it comes to the level of documentation, it's just one of those judgement calls you have to leave up to each programmer and hope you've hired people that will guess the right amount to use in that situation. Also, I think it's funny how many comments there are on a post titled "No Comment" :) Attempting to define the perfect policy on comments is a no-win situation.  Some people want a lot, others want little to none.  Everyone has a different workflow and is expecting different things.  For those of you trying to sell a middle-ware product your preference is largely irrelevant, or should be.
<b>What do your customers want?</b>
Do they want heavy amounts of API and line documentation?  Code that’s easy to read? A lot of system documentation?  The answer to all of these is going to likely be Yes if you ask them.
You certainly shouldn’t ask people a trick question about their preference about comments.  I don’t have the right answer when it comes to the level of documentation, it’s just one of those judgement calls you have to leave up to each programmer and hope you’ve hired people that will guess the right amount to use in that situation.
Also, I think it’s funny how many comments there are on a post titled “No Comment” :)

]]>
By: Kevin Gadd/2011/03/28/no-comment/#comment-2077 Kevin Gadd Mon, 28 Mar 2011 15:50:19 +0000 The article isn't talking about document generator information (something I abhor). The article isn’t talking about document generator information (something I abhor).

]]>
By: Dylan Cuthbert/2011/03/28/no-comment/#comment-2073 Dylan Cuthbert Mon, 28 Mar 2011 14:43:46 +0000 A good interview question is a question that spawns a discussion and gives the candidate an opportunity to defend and argument his stance on the subject. I think this one is much better than questions that rely on memorized tricks (like some clever bit hacks) or vague questions unrelated to programming (about moving mountains and water temperature in hotels). A good interview question is a question that spawns a discussion and gives the candidate an opportunity to defend and argument his stance on the subject. I think this one is much better than questions that rely on memorized tricks (like some clever bit hacks) or vague questions unrelated to programming (about moving mountains and water temperature in hotels).

]]>
By: snake5/2011/03/28/no-comment/#comment-2069 snake5 Mon, 28 Mar 2011 12:59:44 +0000 Great post! Sums up my thoughts pretty much. In my experience an outdated comment will often be worse than having no comment at all. Actually one could even argue that code comments will often be code smells, because they often appear with nifty code hacks, which need explanation why they even work. Most often it would be better to refactor for simplicity instead of just adding a comment to your wizardy (unless there are certain restrictions like performance or API dependencies, of course). Great post! Sums up my thoughts pretty much. In my experience an outdated comment will often be worse than having no comment at all.
Actually one could even argue that code comments will often be code smells, because they often appear with nifty code hacks, which need explanation why they even work. Most often it would be better to refactor for simplicity instead of just adding a comment to your wizardy (unless there are certain restrictions like performance or API dependencies, of course).

]]>
By: Cam Jackson/2011/03/28/no-comment/#comment-2065 Cam Jackson Mon, 28 Mar 2011 12:15:37 +0000 So why do you ask this interview question? What do you learn about a candidate that says "yes I comment my code"? I hate people asking "trick" questions at interviews. So why do you ask this interview question? What do you learn about a candidate that says “yes I comment my code”?

I hate people asking “trick” questions at interviews.

]]>
By: Rob Ashton/2011/03/28/no-comment/#comment-2063 Rob Ashton Mon, 28 Mar 2011 11:03:50 +0000 I keep finding myself wishing another coder or designer had added a glossary, as much as any systems documentation. As typedefs abound to make parameters and returns read in context for problem space there's often an explosion of synonyms, with syntactic and semantic abuses. Passing an ActiveCharacterList to ProcessCharacterIntent returns an ActiveCharacterProcessedArray, and we have to alt-g furiously to find if the original type's dynamic, threadsafe, available on SPU and so on. It's then magnified when disfferent teams use the same name in different namespaces based on different types. Someone notices this and appends 'vector' to all the ends of the vector types, which makes the code less readable and still doesn't help where types have hidden signedness and so on. Re-reading what's become a rant, we should glossary to our code, but also decribe in variable names rather than create yet another typedef for an unsigned int. I keep finding myself wishing another coder or designer had added a glossary, as much as any systems documentation.
As typedefs abound to make parameters and returns read in context for problem space there’s often an explosion of synonyms, with syntactic and semantic abuses. Passing an ActiveCharacterList to ProcessCharacterIntent returns an ActiveCharacterProcessedArray, and we have to alt-g furiously to find if the original type’s dynamic, threadsafe, available on SPU and so on. It’s then magnified when disfferent teams use the same name in different namespaces based on different types. Someone notices this and appends ‘vector’ to all the ends of the vector types, which makes the code less readable and still doesn’t help where types have hidden signedness and so on.
Re-reading what’s become a rant, we should glossary to our code, but also decribe in variable names rather than create yet another typedef for an unsigned int.

]]>
By: Richard Fine/2011/03/28/no-comment/#comment-2061 Richard Fine Mon, 28 Mar 2011 10:54:38 +0000 Reading and understanding code aren't goals in themselves, though: the goal is to be easily able to <em>maintain</em> the code, and commenting more than is necessary makes maintenance <em>harder</em>, not easier, because every change to code has to be matched by changes to comments. It's a very frequent thing I've seen that a comment on a block of code will be wrong - referring to absent variables, or, worse, describing behavior that isn't there - and a lot of time can be wasted trying to reconcile the comment with the code, when really the coder should just ignore the comment and trust what they think the code is <em>actually</em> doing. Caring about whether people use /*comments*/ or //comments, or how they indent their comments - <em>those</em> are things that it's fairly pointless talking about. But talking about whether comments should be present at all is definitely worthwhile. Reading and understanding code aren’t goals in themselves, though: the goal is to be easily able to maintain the code, and commenting more than is necessary makes maintenance harder, not easier, because every change to code has to be matched by changes to comments.

It’s a very frequent thing I’ve seen that a comment on a block of code will be wrong – referring to absent variables, or, worse, describing behavior that isn’t there – and a lot of time can be wasted trying to reconcile the comment with the code, when really the coder should just ignore the comment and trust what they think the code is actually doing.

Caring about whether people use /*comments*/ or //comments, or how they indent their comments – those are things that it’s fairly pointless talking about. But talking about whether comments should be present at all is definitely worthwhile.

]]>
By: Kevin Gadd/2011/03/28/no-comment/#comment-2059 Kevin Gadd Mon, 28 Mar 2011 10:48:56 +0000 Who cares how the code is commented as long as you can read it and understand it? It seems silly to berate people for commenting too much - a little elitist perhaps? "Do you comment your code?" should NOT be a trick question in an interview, you will give yourself a bad image. I quite often put comments in to add a little more "story" to the code. It makes the code more enjoyable to read and gives it some "merihari" (a japanese term which kind of means "balance" but in a deeper way than the english word). Who cares how the code is commented as long as you can read it and understand it? It seems silly to berate people for commenting too much – a little elitist perhaps? “Do you comment your code?” should NOT be a trick question in an interview, you will give yourself a bad image.

I quite often put comments in to add a little more “story” to the code. It makes the code more enjoyable to read and gives it some “merihari” (a japanese term which kind of means “balance” but in a deeper way than the english word).

]]>
By: Francesco Carucci /2011/03/28/no-comment/#comment-2057 Francesco Carucci  Mon, 28 Mar 2011 10:30:18 +0000 In general, I think people should spend less time on comments and more on system documentation. Where you get stuck with an API is often not in the question "what does this function do" (that is usually easy enough to find out unless you are dealing with really bad code) but rather in "how are all these concepts and classes supposed to fit together". Of course, writing good system documentation requires real writing skill and is a lot harder than just slapping on formulaic doxygen comments. In general, I think people should spend less time on comments and more on system documentation. Where you get stuck with an API is often not in the question “what does this function do” (that is usually easy enough to find out unless you are dealing with really bad code) but rather in “how are all these concepts and classes supposed to fit together”.

Of course, writing good system documentation requires real writing skill and is a lot harder than just slapping on formulaic doxygen comments.

]]>
By: Jens Schöbel/2011/03/28/no-comment/#comment-2055 Jens Schöbel Mon, 28 Mar 2011 10:19:12 +0000 self-explanatory code.

]]>
By: Aurélien Pocheville/2011/03/28/no-comment/#comment-2054 Aurélien Pocheville Mon, 28 Mar 2011 10:17:12 +0000