Comments On Code Comments?

theodp writes "It seems like comments are on programmers' minds these days. The problem with comments, as Zachary Voase sees it, is that our editors display comments in such a way as to be ignored by the programmer. And over at Scripting News, Dave Winer shares some comments on comments, noting how outlining features allow programmers to see and hide comments as desired. 'The important thing is that with elision (expand/collapse),' explains Winer, 'comments don't take up visual space so there's no penalty for fully explaining the work. Without this ability there's an impossible tradeoff between comments and the clarity of comment-free code.' Winer also makes the case for providing links in his code to external 'worknotes.' So, what are your thoughts on useful commenting practices or features, either implemented or on your wishlist?"

Comments

Doesn't matter in the end

[crazyjj]

Changing the color of the comments, or making them collapsible/non-collapsible isn't going to have any meaningful impact. A rushed or sloppy coder is going to ignore them either way. And a conscientious coder is going to read them regardless.

The real problem with comments isn't their color, it's when they AREN'T THERE AT ALL. You could have the damn things flashing in rainbow colors and it still wouldn't change the fact that the legacy code I'm going over was done by a sloppy piece of shit who never wrote any comments in the first place, or who wrote cryptic/indecipherable comments that would take a linguist 10 years to translate into meaningful English.

Now, if you'll excuse me, I've got to go play Sherlock Holmes with some strange method written by an Indian contractor whose only comment on it was "This move thing around."

Re:Doesn't matter in the end

[garcia]

The real problem with comments isn't their color, it's when they AREN'T THERE AT ALL.

THIS. I deal with sloppy coding convention all the time but at least when the code is commented I can get a mile-high view of what each section is doing w/o having to spend time carefully piecing the work apart to figure out what happened.

The lack of comments for others is annoying but I really want to know how people go back into their own code several weeks (or even days) later and know what the hell they did when there are no comments.

Many times I have run across a commented section of code that reads something like:

/* Attention future Bill: this section of code sucks and it looks horrendous and awful but I wrote it under a tight deadline. Just hit F3 and let the bitch run; it works, I promise. */

I can only shake my head at myself ;-)

Re:Doesn't matter in the end

[Anonymous Coward]

if you can't fit the documentation into your method (and variable names), that method is likely too long and complicated.

Re:Doesn't matter in the end

[Dan Dankleton]

Not necessarily. Good code can show what is being done, but it can't show different approaches which were rejected. Comments can explain why certain shortcuts are valid or not valid in a way which won't be obvious from the code.

Re:Doesn't matter in the end

[crazyjj]

/* Attention future Bill: this section of code sucks and it looks horrendous and awful but I wrote it under a tight deadline. Just hit F3 and let the bitch run; it works, I promise. */

Makes you want to kill Bill, doesn't it?

Re:Doesn't matter in the end

[Simon Brooke]

if you can't fit the documentation into your method (and variable names), that method is likely too long and complicated.

This is foolish arrogance. In my thirty years in this profession I have worked with many people who thought their code was 'self documenting'; all of them were wrong, and faced with their own code two years later I doubt any of them could immediately follow it. I've only ever worked with one software engineer who, in my opinion, documented enough; I strive to match his standards in my own code but I know I don't always succeed.

There are, in effect, three reasons for not documenting:

Arrogance 'My code is so clear and elegant it needs no documentation' Procrastination 'I'm too busy just now, I'll do it later' Obscurantism 'If I don't document my code, no-one else will be able to understand it so they can't sack me'

These days I see poor documentation practice as a reason to negatively appraise an engineer; if it doesn't improve I'd seek to move them off my team. There's no excuse. Documentation - like source code - isn't, fundamentally, for you: it's to communicate with your colleagues and to the poor grunt who has to try to maintain your code, long after you've moved on to more interesting projects. And that poor grunt may not be as intellectually gifted as you are.

Re:Doesn't matter in the end

[Tx]

The problem with that is there seem to be a lot of people who say, and possibly even believe, that their code is clean and self documenting, when in fact it is anything but. I would say that such people outnumber those who actually do write clean and self-documenting code by a significant margin. In those cases, where you find yourself looking at this code and realise you have no idea whatsoever what it's trying to achieve, much less whether it's doing it right or not, and you're thinking "just give me a f*@king clue, goddammit", any sort of comment, even a cryptic, half-assed effort, can be a lot better than nothing.

Re:Doesn't matter in the end

[dkleinsc]

Not at all:
1. Sometimes you're using a confusing and complex feature of some library or server. Providing a comment with a link to the documentation on that feature makes things a lot easier for the next person to come along.

2. Sometimes you're working around a bug in a library. You should leave a comment explaining what the mis-behavior was.

3. Sometimes you're implementing an algorithm that's relatively new academic work. Adding a comment explaining exactly what this is, where you can find it, and why you're using it here will help somebody learn more about it.

4. While expressive code can explain what you are doing, it can't explain why you're doing it. If your method is called "zoich_the_fleemoid", your comments about this should probably provide some kind of indication of what a fleemoid is and why you'd want to zoich it.

5. Anything residing on a major code boundary (e.g. a library method relied on by other developers) should get the full round of documentation - what it does, what it accepts as parameters, what it does with those parameters, what it returns, and what side effects are expected. Yes, your code should be clear enough that the other devs could learn this stuff by reading your code, but they shouldn't have to dive into it to figure out what your APIs do.

It's a very rare case where I think a programmer wrote too many comments.

Re:Doesn't matter in the end

[v1]

That brought a smile to my face. More than a few times I've put in comments like "yes it's doing it this way for a reason. don't try to optimize it by doing xyz, it doesn't correctly handle exceptional cases x and y. leave it alone."

I don't have a good memory, and my comments are for me as well as for others, even in projects that will never be seen by another living soul. Many times I've looked over some code and thought "that would work better / be so much cleaner if I changed that..." only to see one of my warnings that it had already been attempted and lead to unexpected complications.

But I would like to see more of an option to "collapse" comments. I usually place a comment block above every functional block of code. Most of the time I just need to see a quick one-liner reminding me what all that block does. Other times I need specifics like "this stuff is set on entry, and these things are set on exit" etc. But the detailed comments eat up a lot of screen space and make it take longer to scroll through code looking for things. I'd like to be able to have expandable/collapsable comment details. On a global basis.

Re:Doesn't matter in the end

[RabidReindeer]

I was very amused when Donald Knuth announced Literate Programming, since I'd been doing something quite similar for years, although there weren't any automated tools back then.

First I wrote WHAT the function was supposed to do. This was the comments.

Then, I wrote the code to DO it.

If I did the job right - and kept the comments up to date (people really manage to do that?), then when I came back to make fixes or improvements, I'd know what the code was doing and what the likely consequences of changing it could be. Including the less obvious ones, such as things that depended on subsidiary routines.

I have extra incentive to write good comments these days. Back then, major systems often had program logic manuals. These days, the apps are more complex, but the time to sit down and write a PLM is rarely there. However, if the comments were well-done, tools like Oxygen and Javadoc can generate a fairly decent substitute.

Re:Doesn't matter in the end

[c 0xFF]

Code, by definition, tells the computer how to do something, but not why. The computer doesn't care why it's adding two numbers together, it just obeys.

Likewise, self-documenting code will only ever tell the programmer how the computer does something, but will never tell the programmer why. That's the job of the comments.

The problem is that most people focus on "how comments," instead of "why comments." They spend their time on the function comment block, describing even the most mundane function in detail (but never actually saying when to use the function or how the algorithm works). Or they spend their time on the comment block at the start of the file (doing the job of your version control software). (The occasional "signpost" comment is a good idea, of course, as is documenting the API. Some "how comments" are still very useful.)

Re:Doesn't matter in the end

[jythie]

That is one of my major complaints. When time is short and changes are being made fast and furiously, or prototyping is being done, time spent commenting comes out of time getting something completed under a harsh deadline... which means comments are often not updated to reflect the new state of the code.. and incorrect comments can often be worse then no comments at all.

Re:Doesn't matter in the end

[TheSpoom]

So basically you are stupid and cannot understand code. What other reasons are there to write cute little comments?

Ah yes, the arrogance category. Thank you for your example.

Re:Doesn't matter in the end

[serviscope_minor]

Likewise, self-documenting code will only ever tell the programmer how the computer does something, but will never tell the programmer why. That's the job of the comments.

Yes.

Hands up who has seen a piece of code like this:

//Add 1 to i
i++;

Bonus points if it's pre/proceeded by a complex block of uncommented, impeneterable code.

Re:Doesn't matter in the end

[EmperorOfCanada]

Agreed. I find commenting is a good diagnoses for either OCD or micromanagement by a quasi non programmer. It drives me bonkers to see a function like this:

//*********
//GetNumberOfUsers is a function that will return an integer
//describing the number of users that match the parameters entered
//category_id is an integer containing the category of user
//country_id is an integer containing the country code
//company_id is an integer containing the company identifier.
//Created:BOB_MILLER:2008-08-09:14:24:34
//Edited:BOB_MILLER:2008-08-09:14:24:39
//Edited:BOB_MILLER:2008-08-29:10:24:39
//Edited:BOB_MILLER:2008-09-09:16:24:39
int GetNumberOfUsers(int category_id, int country_id, int company_id)
{
//this will hold the number of users
int num_users=0;
//Get a connection to the database
DBConnection db=new DatabaseConnection('central_database');
//check to see if connection is good
if(db==null){explode();}
//good didn't explode so do next statement
...
//Close database connection
db->Close();
//Now return the number of users
return num_users;
}//GetNumberOfUsers(int category_id, int country_id, int company_id, int some_param_that_used_to_be_here)



The key information should be put into the naming of the variables, functions, and classes. Comments should be reserved for almost a conversation with another programmer. Magically perfect code should in theory have zero comments.

x=x+1; //This compiler acting is screwy so I didn't use the more efficient x++ here
x=sqrt(sin(log(y)/pi)*e);// this is the lambert/highlander formula
x=lookup_table[y]; //This look-up table speeds things up by 100x.
x=sin(tan(cos(x)));// If I knew my trig better there must be a better way to condense and speed this up.

Re:Doesn't matter in the end

[Jake Griffin]

That's why you have TEST CASES for cases x and y; so that if someone ignores the comment, tests will break alerting of an issue!

Re:Doesn't matter in the end

[ShanghaiBill]

And then the how changes....

// Add 1 to i
i+=2;

I have seen worse. I worked on a project that had a lot of "magic numbers" in the code, so our manager told us to make symbolic definitions for them. One guy put this in a header file:

#define FOUR 4

and then used FOUR everytime he needed that number. Then, you guessed it, someone decided that 4 was too few, so they changed the defintion to this:

#define FOUR 5

In My Opinion This Is a Non-Story

[eldavojohn]

There's not much material to those links -- at least nothing even close to addressing the full problem. The "adjusted" code in the first link is trivial. Furthermore, that is how we comment code where I work. I'm surprised there isn't an annotation driven doc-generating friendly comment block at the top of that signature in their example (along with the inline comments)!

The reason editors let you collapse comments is that you sometimes have to make really ugly code -- whether it's for performance or time constraints. And the only way to really describe it actually larger inline blocks that can obfuscate the code. So they make them collapsible for those who have read them already.

Winer also makes the case for providing links in his code to external 'worknotes.'

Yeah, we use an internal wiki.

So, what are your thoughts on useful commenting practices or features, either implemented or on your wishlist?

The biggest complaint I have is people who use comments to explain bad object/procedure/function/method/script/class/whatever naming. For example, a guy I worked with calls everything a "driver." Main method? That's a driver. Class holding the main method? Of course DriverClass. Package? Of course YYY.ZZZ.NNN.Driver. On it goes. Another guy likes to use the verb "interrogate" where as I like to use the verb "inspect" and I think that's just more about your origins (I think he's Spring background while I'm a little more on the Ruby/Groovy side of things). A common and well defined vocabulary inside your team and embedded in your actual code will take you much further than trying to explain it all out in the comments.

Getting developers to comment

[laffer1]

At my current job, most of the developers think commenting is weak. I've dealt with this problem before, but it's awkward when I'm the only one that wants to comment. Funny thing is, every time we hit a program that a former developer wrote that my boss can't understand, he makes us rewrite it. Having comments in the code might save a lot of development time.

When I managed a team, I required commented code. It saved our butts more times than I can count. I also use it to look for bugs. It's amazing what code review can do a few weeks after you wrote something or having another developer look at. When code doesn't match comments, there's a bug.

Good comments are good.

[darkwing_bmf]

I don't really understand why we're going over this for the 50 thousandth time on slashdot, but as always, good comments are good, bad comments are bad. Comments that describe the interface of the function you created and how its supposed to be used are good. Comments that say "increment the variable" are worthless and perhaps worse than worthless as they add maintenance problems when the underlying code is later changed and nobody bothers to change the comments as well.

Removing comments from code

[Latent Heat]

I think it is a good design rule that if you have a comment describing some inglorious hack, maybe you could rewrite the code to remove the comment along with the hack?

I also think that comments describing interfaces are better than comments describing processes. This is the old thing of "describe what the module does and leave the description of how the module does what it does to reading the actual code." So preambles describing the parameters a function takes and valid ranges on those parameters are most useful.

The other thing about comments is not so much the writing of them but the keeping them up to date. The compiler doesn't check that the comment is still relevant to a function you have changed.

Re:Removing comments from code

[RobertLTux]

in the case of some inglorius hacks documenting WHAT YOU WERE DRINKING at the time may be the most useful (or what you were on or the fact that you were on hour 47 of your shift...)

What other engineering disciplines do.

[trout007]

I'm a mechanical engineer. Our "code" is models and drawings. These are what represent the real world objects in our designs. But you don't just deliver a set of drawings as a product. You have Analysis Reports, Design Manuals, Operation Manuals, Maintenance Manuals, Parts Lists, Concept of Operations, and about 20 other documents that describe the system you built. Sometimes a good engineer can pick up the drawing package and figure out how the thing works. But if you really want to understand the design you have to read the other products. If those products don't exist you end up reverse engineering from the design.

It depends on the comments

[betterunixthanunix]

"This does not work"

"What the f*** is this doing?"

"TODO: fix"

All of the above are useless comments, yet they seem to sneak into everything. Worse still are comments that are meaningless to anyone who did not write them, or comments that make reference to undocumented conversations (e.g. "This is the implementation we spoke about on Tuesday").

Don't waste time writing useless comments. If you do not have time to fix a function, the comment should explain what needs fixing so that someone else can do it without first spending half a day debugging.

Don't mind me

[Sez Zero]

I'm just here for the Comments on Comments on Code Comments.

Re:Save time

[ShanghaiBill]

Comment first, fill in the code later.

Yes. And as you write the code, make it clear enough that you can then eliminate the comments. If your comments are this:

// process command line arguments
// read input files
// process the data
// output the results

Then your code should look something like this:

void
main(int argc, char *argv[])
{
    processCommandLineArguments(&argc, &argv);
    readInputFiles();
    processData();
    outputResults();
}

and now the comments are no longer needed. So you should write comments first, then write the code, then look at each comment and try to eliminate it by making the code clear enough that the comment is superfluous.

Re:Write clear code, remove comments

[Dixie_Flatline]

Comments aren't just there to explain the code. Of course you should write clear code. But I work in the games industry; there are times where clear code is thrown under the bus for the sake of efficiency. There are annoying convoluted constructs that are optimisations but they read like someone just showing off.

But this speaks to a fundamental misunderstanding of what comments are for. You're not explaining the code, you're explaining the algorithm and the basic thing that your code is meant to accomplish. You don't write comments to let people know that you're looping over an array, you write comments to let people know WHY you're looping over an array and why they should care. I'm all for verbose variable names, but if you're going over 132 columns I'm already irritated. Go on for 80 more and it's tremendously annoying to read the 'clear' code.

There are a lot of different ways to solve problems. Ideally, your comments should lay out what your thought process was when you were solving this particular problem. If you leave, someone will understand the problem you were trying to solve, and that context makes reading the code easier.

And even if you don't leave, it's a good shortcut for yourself if you have to come back to that code several years later. I've saved myself a lot of time by commenting things well. Five years is long enough for my thought process and problem solving methods to change, so when I look at the code and wonder why in the hell I did something in such a dumb way, the comments tell me what was going through my inexperienced head.

Lastly, and perhaps most importantly, humans don't agree on the meanings of words. There is some research (that I've read in passing; no citations at the moment) that says that we all have our own meaning of words, and we all speak completely unique languages that just happen to overlap with other people's unique languages. To write code that is universally understandable, you need to write code that has a completely unambiguous context to all people at all times (well, more or less). As someone that works in a heavily bilingual office (in Montreal), you can't guarantee that the programmer before you had the same interpretation of things that you do.

All comments are lies.

[famebait]

That sounds harsh, and of course it doesn't fit 100% of the time, but if you look closely enough it is true a frightening part of it.

The only thing you can trust is the code.

When I write comments it is usually to say "this code might look like an opportunity for this or that refactoring/optimisation. Don't do it becauase..."
Yes, ideally the code should express this directly, and commetns are an admission of defeat, but sometimes we are defeated.

Re:Write clear code, remove comments

[MrSenile]

Ok.

And if I'm off the street, new to the company and see your line:

processCommandLineArguments(&argc, &argv);

Sure, I know what the function -likely- does, based on the name.

Now how about the other questions.
1. why does it need to process the command line arguments.
2. what are the command line arguments that you are passing in.
3. what is the error control of that function if given improper values.
4. what is the error control of that function if given too many values.
5. how many arguments total can it handle.
6. what is the syntax it expects for the arguments
7. are there any global variables being defined or redefined in that function.


You take a lot of things for granted that a lot of other developers will be looking for.

This, is why documentation is needed. I don't believe at all it's an admission of defeat. I believe it's an earmark of a beautiful programmer. Just because your code is insanely clean and documented, in itself, does not mean you should omit the block of description for variable calls, error return calls, exceptions, limits, and any global declarations. And while including this into a centralized wiki is good, I'm sure coders will not be inspired to cross-reference a program with a wiki and keep doing searches for function names. It breaks down their train of thought and frankly slows down productivity.

Assuming others can just understand it without the documents would be arrogance.