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

[Anonymous Coward]

Going even further - good code generally doesn't need a whole lot of commenting. If you are struggling with this problem of how to display comments, then that says a LOT more about your code than your comments.

(That said, trying to deal with a legacy system, comments can be helpful.)

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

[Valor958]

For the legacy coding point, I'd like to make one suggestion on commenting. At the time that code was written, it wasn't 'legacy' code... but they still chose to comment (however poorly). I would suggest commenting where ever possible to clarify intent as you never know who will be fixing your code, and when people will be complaining that IT is legacy code. For the relatively minor amount of coding I have directly done, I commented a reasonable amount so as to locate code segments quickly and for others referencing my work to do the same for any debugging. Oh... and now, that code is considered legacy due to the nth-teen revisions made on it since 2002.

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

[Rob the Bold]

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 ;-)

Preach! If anyone needs an argument for readable code and appropriate comments, it's this above, perhaps paraphrased: "The poor slob maintaining your work may be you."

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

[ciotog]

// TODO: fix this Not all comments give you a mile high view. Some are just pointless wastes of disk space...

I don't see anything wrong with flagging a section of code with "TODO"... It at least let's the next person know that the code might be incomplete/buggy

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

[Anonymous Coward]

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.

[...]

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.

I always write comments with the thought in mind that the poor bastard who has to maintain this code years from now might turn out to be me.

Re:Doesn't matter in the end

[jandersen]

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

Bad comments are worse than no comments. And good comments become bad when they are not being maintained along with the code.

I think it is a question of attitude; people in general do not think of documentation and comments as being as important as the code, and it starts at management level. But there is another side to this problem: people have not been taught how to comment well, so actually, the problem to some extent starts even before project leaders get their grubby hands on things.

And writing good comments isn't easy; but I think the best way is to write relatively few, relatively large blocks of explanations, which DO NOT point out the obvious, but explain things like which part of the code the comment concerns, what the parameters and return value mean (not what they are, what they mean) and how other parts of the environment influence the execution. And not least, how and why this code is deviates from what you would expect to find, if applicable.

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

[Hillgiant]

If your comments are not getting updated, then I suspect you have very poor revision control. I recommend that you take a step back and consider why you are revising the code in the first place. Once you understand why, you need to document it for the next poor sap (recognizing that YOU might be the sap). Only then should you consider how the code should be changed.

Re:Doesn't matter in the end

[digitalaudiorock]

I couldn't agree more. No matter how well you code there are always reasons for comments...especially when the nature of what the code is trying to accomplish is complex. Even if your code is perfectly structured and understandable by any good programmer, making someone else reverse engineer that is inexcusable. Another example is when your code needs to do something in what may appear to be round about or unusual manner for some specific reason...because, for example, a more obvious approach causes some sort of problems...that is, so someone doesn't come along and try to "fix" it.

People have a lot of weird ideas about comments, and I don't get it. It seems pretty clear to me what parts of my code require some sort of explanation...and not just for someone else, but for me as well. I can't tell you how many times I've read my own comments to remember why I took a specific approach to something.

Re:Doesn't matter in the end

[Hillgiant]

So basically you are stupid and cannot explain design choices. What other reasons are there to not document it?

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

[locofungus]

Exactly my point.

The people who write code like this don't know what it is doing when they write it. Therefore, by definition, at best their comments will tell you what they *meant* to write.

Given that this code is now 10, 15, 20 years old, other programmers along the way will now be relying on what this code *actually* does.

It's one of my pet peeves that people want to rewrite code when they *can't* understand it. But in order to rewrite code like this you *have* to understand it. I've seen so much rewritten code that is even worse than the code it replaced because it's full of hacks reproducing all the accidental behaviour in the original code and introducing its own accidental behaviour along the way.

It is a wonderful thing to be given the chance to rewrite a piece of obnoxious code. But it's an expensive process with a lot of up front research and, is always harder than fixing that obscure bug in the obscure code *except* when you've already proved that the obscure bug *cannot* be fixed in the old code. But in that case you're already admitting that the rewrite will change some behaviours.

Tim.

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

[Zero__Kelvin]

"You implement a solution, then you experience a bug for which you write a test case."

Great example of the implications of Godel incompleteness! Unit Tests are awesome, as are other kinds of automated tests, but they are not without their own problems. Say I fall for your argument of adding levels of indirection to the documentation and go to the test for the answer. Will I then find the why of the implementation? Will I find important information about the code, like that it does something different than the documentation says because the documentation is in error for version x.y of the API, and that I should change it back to the documented method if they fix the API in a later version? If yes, have I not then still documented the code with comments? If no, wouldn't I make a better Janitor than programmer?

Re:Doesn't matter in the end

[nschubach]

Otherwise, the comments end up being a ton of useless bloat that just makes things harder to understand, not easier.

This right here is more of the reason I completely skip comments when reading code. I haven't read much code where the comments put any valuable content that the code didn't explain better.

Re:Doesn't matter in the end

[SDF-7]

Yeah, that sounds much more efficient. Nothing like letting the developer work through the (bad) optimization design, code it... get the test failure and then waste more time debugging it instead of just warning them off up front.

Belts and suspenders -- test your corner cases, but document the pitfalls.

Re:Doesn't matter in the end

[SuricouRaven]

My comments tend to be more along the lines of 'Don't quite know how I wrote this, but it seems to function.' I'm just a hobbyist, but I suspect that more than a few mega-corp software engineering projects are the same. At least I don't use 0xB00B135

Re:Doesn't matter in the end

[SuricouRaven]

If I saw that, I'd conclude that the convert-to-string bit was put in first, and the make-it-lowercase a later addition to the code.

Re:Doesn't matter in the end

[Jake Griffin]

I'm not saying that you shouldn't document it too. Sorry for misleading you. I'm all for documentation of these things too. But people frequently ignore documentation, so having the test case there too helps to prevent broken code from getting into production.

Re:Doesn't matter in the end

[mypalmike]

It seems every single anti-commenting post in this thread is posted AC. There's a reason for this.

Re:Doesn't matter in the end

[Bigby]

Those shortcuts are not obvious at the time of coding. I always go back to my code weeks later, when I forgot what I wrote. Then refactor and comment where appropriate.

Re:Doesn't matter in the end

[Eponymous Hero]

what i see the most is there's no separate set of eyes looking at a bit of code about to be released to production. the developer is left to test his own work (usually without test suites, because if you have those then you are probably not the only one looking at the code either), and there are so many ways he can get it to work on his own machine while it breaks for everyone else. bigger companies/bigger projects will have a qa/qc/uat/whatever process before release, but it seems like the majority of programmers are cowboys who trust themselves way too much.

Re:Doesn't matter in the end

[richlv]

code usually will not tell you why something is done this or that way. at most it will tell you how it is done (and even then, not always).

also, even when you think you know what exactly code does, you usually do not see the "big picture". in any software that's more complex than a few operations there will be algorithms that can not be understood from a couple of functions. this is where comments can help enormously, as the overall logic can help to avoid silly mistakes.

the problem with "code does not match comments" is that... the project is done anyway. if that is the case, code quality is so horrible, nothing good can come out of it.

another somewhat interesting thing is that in way too many cases, when talking about slightly more obscure low level operations, nobody really knows how it should work - unless there's a comment somewhere, explaining what and why is done there. yeah, one can figure what the code does, and there might some ugly hack in there. so that is kinda cleaned up, only to discover two months later that the old logic was correct (as impossible it seemed two months ago...), just some asshole did not bother adding a comment about it.

Re:Doesn't matter in the end

[TemporalBeing]

What I do is put my comments in the same line as the code. When I need to read the comment I just scroll right, but otherwise it doesn't distract me or eats up screen space. If it's too long, I split it up between different parts of the code. For example, I explain what a function does in the line before it, but I detail how it does that (if explanation is necessary) in the body after the lines.

One of my colleagues puts all the comments in his code in a certain column at the right side, typically on the same line as the code itself (following the GNU coding-style). While the comments are useful, they are completely useless in that location; it would be far better to have them on the preceeding line, or in a larger block so that it can actually be seen without scrolling the screen left/right.

Re:Doesn't matter in the end

[James McGuigan]

When writing computer code, and either using or reusing previous sections of code, the key question is how much mental energy and attention units will it take for the next programmer (who may be you in a months time), to gain a workable understanding of the function.

As humans, we only have attention units enough to keep a limited subset of items (maybe 5-7) in our heads at any one time.

If code is badly written and/or documented, then its going to take more mental energy (and time) to relearn the code than it would otherwise. This is time and energy that could be better spent solving useful programming tasks.

Generally I believe functions, especially those in reusable library code, should be well documented in terms of inputs, outputs, plus any assertions, assumptions, exceptions and with a view to programming by contract. Static languages like Java force you to do alot of this in terms of syntax and compiler checks, but for dynamic languages like javascript, the language doesn't enforce this and thus the explicit effort is required to add this information in the form of function, class and variable documentation.

Inline comments should assume the reader is able to read the code itself, but should describe any hidden implications, design tradeoffs, links to useful external documentation, gotchas, bugs etc. Its also often useful to give inline examples of the data is likely to process, such as HTML strings or JSON data hashes, especially when the structure is not statically defined by the language. The sort of things that are not obvious from directly reading the code itself or would require time to go off and google or lookup in another file.

Here are a selection of useful inline javascript comments from my own codebase archives:

data.values = {}; // {Hash} = {Number}

eventManager: null, // {EventManager} reference to js/libs/EventManager.js, passed in via init.js

delay = delay || 10; // 10ms is enough time for this.el.target:mouseenter to trigger

tooltips: $([]), // empty jQuery - shared between all instances of this class

typeof a === "function"; // Oops, false in IE and Opera, true in FF and Safari ("object")

listenerId: "_" + (++this.lastListenerId), // BUGFIX: Chrome does array ordering, rather than insertion ordering for hashes with numeric indexes
// Force syncronous browser caching to ensure all files are in order, bug in Opera and IE
// if( !this.contexts[uidType][contextUid] ) { continue; } // if the contextUid has no associated listeners, no point looking for them
// Context is required, listenerIds for a context can be looked up via this.contexts[uidType][contextUid]
// Loop over uids in json - should be faster if json.keys().length is smaller than this.listeners[uidType].keys().length - TODO: profile
// Read attribute, overrides this.options.ajaxRewrite
// If you want a double slider, this.el.selects needs contain two select elements
// Ensure that specified data range actually covers given data
// This really should be part of this.parseOptions(), but we need access to this.xy.valueSpacing
// HACK: Do the loop twice, starting from the origin. In theory we should be able to do this a single loop
// Note all angles in radians. circle = 2 pi radians
// Just check if the total is 0 and draw circle as fallback
// Note: Object literals declared here will shared between all instances

this.wrapper.height( this.getInitHeight() ); // Canvas is position absolute so we need to explictly define wrapper size
// fadeOut when the mouse is over the tooltip

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

Re:Doesn't matter in the end

[Rob Kaper]

The "TODO" flag isn't what's wrong there, the "this" part is. It's obvious that the TODO relates to the nearby code (this, not that). It's still not obvious what needs to be fixed. It could be a lack of performance, error handling, input validation. Some use-cases/states/values might not be covered/tested/identified or implemented. But the answer is always: why. Ask yourself "why am I adding a comment here" and the answer is the perfect comment.

Re:Doesn't matter in the end

[mark-t]

I've seen similar things many times in my career, and I've come to call them "anti-comments", because they describe something that is *NOT* what the code it is supposed to be commenting is doing.

Contrast

[Bogtha]

If your aim is to make something more visible, don't pick a yellow-on-white colour scheme.

Re:Contrast

[crazyjj]

Could be worse. They could use white on white.

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.

Re:In My Opinion This Is a Non-Story

[antifoidulus]

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.

Lets not forget (probably misguided) policy. A lot of places have policies that say you MUST have multi-line comments for each class/function/whatever. Being able to collapse those down makes it a lot easier to just bypass such forced comments.

Use vi

[Anonymous Coward]

Use vi. Always works for me.

There's No Impetus for Comments

[Anonymous Coward]

...because most organizations are total failures that make you write and maintain thousands of pages of "design" documents that are actually just the code-base itself converted line-by-line to English sentences. Thus, no comments are ever written, because the developers are already maintaining two instances of the entire code-base.

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.

Re:Getting developers to comment

[Dixie_Flatline]

Not at all. Extremely complex systems can be hard to trace the codepath through. Someone putting comments into a function to explain how it interacts in the greater scheme of things can be extremely helpful.

Comments aren't meant to explain code. You should be able to read a for loop. But if I'm in the middle of a function that's crashing and there's a comment telling me how this function interacts with the SYSTEM, then I can understand the CONTEXT of the code and more easily find the error. Otherwise, it's 20 minutes or an hour of reproducing the problem and then parsing the stack trace and then figuring out where this variable has been modified instead of where it SHOULD have been modified, etc., etc.

Re:Getting developers to comment

[parkinglot777]

What if the code is correct, and the comments are wrong? Sure, that may be a bug in your eyes, but why spend the time writing incorrect comments?

Then go back (or refer) to one of reasons that Simon Brook's comment pointed out -- Procrastination. It is the programmer/developer responsibility to do it at the same time when update codes. The comment concept works if and only if every programmer/developer is at the same level (everyone does it and does it right). If one or more are not, that could easily screw the whole concept of having comments. It is a good practice, but not everyone does good practice.

your coding team members can write sentences better than they can write code

Writing comment does not require to be perfect. An average write up about what it does may be suffice. If you are talking about the time spent in writing comments, then you should already know that it could be as much time spent as in coding. That's normal.

write high quality code

Please define the phrase above. It is too broad and there aren't many (if none) programmers/developers who can actually write a whole software/program codes that are correct, robust, optimal, and maintainable. If you are talking about a module or a small function/method, then I would see that is much more possible. However, it is not practical for real work because it is very rare to use only one function/method/module for a program/software.

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.

Save time

[bill_mcgonigle]

Comment first, fill in the code later.

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:Save time

[medcalf]

Yes, exactly. When I write code anything more than a bog-standard getter/setter method, the first thing I do is write a comment describing everything coming in and everything going out, and how "in" and "out" differ. Then I write a series of comments going through the entire set of steps that have to happen (at 50000' level) to get the in, do the transformation to produce the out, and actually send off the out. For those parts where the 50000' view isn't obvious ("read in the file from the passed filehandle, throwing an exception if you can't" covers it, but "now combine the two streams" doesn't), I break it down further in more comments. Only when I'm sure that the comments are a good approximation of the final flow do I actually write the code. During that process, I eliminate those comments that are now superfluous (for example, because the code is obvious and common, or because the why is otherwise unimportant for that block). The end result is a small increase in the time to write the code, and a vast decrease in the time needed to debug the code, along with dramatically better maintainability.

Re:Save time

[CrazyBillyO]

Sounds similar to the pseudocode programming process.

Re:Save time

[brausch]

This!

The problem with comments ...

[Dark$ide]

Isn't whether they are displayed, isn't wether they exist or not it's whether they add any value, whether they describe why the code has been written in such an obscure way.

There's also nothing worse than a comment that states the bloody obvious. If I'm clearing a register to zero I don't need a comment next to the SR 6,6 or XR 6,6 that is performing that action. I can read the code to see what the bloody code is doing.

The time that code needs a comment is when you're shifting bits or multiplying something by a funky/obscure value for a sensible reason but the reason isn't obvious by simply reading the code.

Also remember you don't get the comments in the post mortem storage dumps when you're trying to fix someone's programming error at 2:30am with a few managers breathing down your neck panicing that it won't be fixed and running by 8:00am.

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

Re:Removing comments from code

[parkinglot777]

"describe what the module does and leave the description of how the module does what it does to reading the actual code."

If I understand you correctly, it means that only one description should be there but not the other? If so, I have to disagree. The description of what module does should be placed on the top of the module, but the description of how the module process should be inside the code (inline). What module does could be taken from the design document; where as, its process is related to the algorithm used. Leaving out the description of the algorithm (process) is similar to encrypting the code because those who inherit the code may not understand why certain thing is there. Both type of descriptions should be there but in different places.

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.

Write clear code, remove comments

[ShanghaiBill]

I used to put a lot of comments in my code. Then I read the book Clean Code, and it changed the way I look at comments. Basically, every comment you leave in your code is an admission of defeat: you were unable to write your code clear enough to eliminate the need for the comment. Today, I write my code with comments, and then I go back and try to eliminate each comment by making the code clearer instead. So instead of

do_args(&argc, &argv); // process command line arguments

I do this:

processCommandLineArguments(&argc, &argv);

and the comment is no longer needed.

Today, my code has far fewer comments, but is easier to read and understand. The few comments that are left are usually block comments that explain why something is done, or outlining how the code could be improved or expanded in the future.

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.

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.

Re:Write clear code, remove comments

[multipartmixed]

You missed the most important one:

8 - Why the hell are you passing in *pointers*? Is your broken-ass processCommandLineArguments() actually going to screw with them?

Re:Write clear code, remove comments

[periodic]

1. I guess it should be obvious why command lines needs to be processed. If there is some special processing then a comment is needed, it the function does what it says, I see no need for comments.

2. This is hopefully documented so even a user can read it. "--help" is a common way of doing this. Then this information can be found in the function itself or by running the program.

3. Should be easy do find from the function interface and how it is used in the code. Also reading the code of the function will help out a lot.

4. Stated in the code of the function.

5. Stated in the code of the function.

6. Combine answer 2 and 4

7. Hopefully no, but yes if it does it needs documentation.

8. Normal in C (Hopefully no modification of the arguments is done, if modifications are done: Comment!) In C++ this would be documented in the function interface f(const type& foo) or f(type& foo). First case tells me no modification is done second that I should expect the value to be modified, in the first case your compiler will check that your design rule of not modifying the argument is followed. Writing the same in a comment will sooner or later be broken and the comment being wrong can cause more headache then trying to understand code.

However documentation about architecture giving an overview of the application and explanations as to why and what each module do is important.

My rule of thumb is if functions do what you think they do no comments are really needed. Comment unexpected behavior or portions of code that are complicated (hopefully for a good reason)

Now if you would write an API where you don't expect programmer to have access to the source code. Documentation and not comments (they can be the same thing but not always the case) is needed.

In my opinion comments that are wrong is more detrimental then no comments.

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.

Collapse the code, not the comments

[Tim Ward]

Then you can read what the code is supposed to do and understand how it is supposed to work.

Next, you uncollapse the comments, see what the code actually does, and fix it.

Comments are usually as good as the code

[ccguy]

In my experience, comments are usually as clever as the writer, and as good as his code. When it's my code and my comments by the way the quality of the comments seems to diminishes as the code ages, even with the file timestamp not changing.

Anyway I remember discussing comments vs self-explaining code with a coworker. Eventually we ended discussing magic numbers (usually they warrant SOME explanation), he just told me he used #defines which made thing a lot more clearer. After the coffee, I checked some of his code:

// Validación de cuenta bancaria
#define ONCE 11
#define DOCE 12

(In Spain bank accounts have a simple check embedded so you can easily verify is a bank account number is incorrect, and the algorithm requires to validate the results of the calculation with the values in positions 11 and 12).

Ignoring the comments is the wise thing to do.

[140Mandak262Jamuna]

Djikstra said, "Always debug the code, not the comments". No one updates the comments. Including me. The number of hours I have wasted in debugging code because I trusted the comment written in the function or the algorithm is countless.

When I was in grad school my thesis guru believed in a tool called fweave and ftangle. You write code in a c like syntax, along with comments that are regular TeX or LaTeX files. Then send the code through fweave and you get a regular TeX formatted document that can be viewed in ghostscript or printed postscript. Send the code through ftangle, you get a valid FORTRAN code that can be compiled and run.

It worked for him because he keeps getting a stream of grad students and the code project has to be perfectly documented for the next student to continue the work. But in companies where technical specialists can occupy a position for many many years along with constant pressure to add features, the first thing that get dropped is code documentation.

For example I have been shipping my product for 16 years now. So many of the functions I write are fleeting and have low half-life. They often start out as a debug function to help me understand some issue, which might not even get checked in. But a few get checked in, first invoked in debug builds alone, then in release builds under env flags, then slowly they morph into sanity check function or an audit method, then a verification procedure, then eventually a special case detector for some feature. When it was first written it does not appear to be worth commenting well. By the time it is part of the feature, it is considered too late to spend resources to comment it.

Re:Clarity

[jsmyth]

Really? So even a simple method that just load some stuff into a hash and then returns the value that matches the key it was given should be commented?

At some point the code is so simple it comments itself.

Sure, because then the next coder, instead of saying

"Huh? Why is he filling a hash only to return a single value?"

can say:

"Oh, that's what he was trying to do. What a kludge. I'll fix it."

...and write it properly.

No comments == Job security

[S_Stout]

Some people like to ensure that operations would be hindered should they be fired.

It's Another Way To Tell What They Were Thinking

[Greyfox]

Programming languages are as much about communication with other programmers as they are about communication with the machine. At some point someone else is going to have to do something with your code, no matter how well written it is. Over the course of my career I've run across countless pieces of code where I've wondered "What the hell was this guy thinking?!" A well placed comment might tell me, if they'd bothered to put one in. Sometimes that construct actually has to be awkward due to the previous design of the code, and changing it will cause breakage or a side effect somewhere else. Most of the time they just weren't putting a lot of thought into the design of that section of code (Or more often, their entire application.) In a handful of cases they had just discovered some feature and had become enamored of it (Like pointers to functions, or ? : branching.)

Subtle clues tell me how much code I'm probably going to have to fix in the maintenance of an application. Comments could tell me if the programmer considered a section of code to be temporary with replacement needed, or if the function I'm looking at is a crucial part of the application. One of the best projects I've ever worked on had the requirements that had driven each function at the front of the function. That made it very easy to focus design and refactoring efforts where they were really needed.

I recently inherited a ten-year-old heap of perl code, on top of which someone had piled a ruby wrapper. There's a lot of functionality that's duplicated between the modules of both languages, and refactoring it all is going to be a nightmare. The code could be in a transitional state where the design is not where I want it for easily a couple of years. I've liberally sprinkled it with todos and comments where I'm putting new code, so the next poor sucker who gets this thing maybe doesn't have to start completely from scratch.

Comment lightly and relevantly

[Terry Pearson]

I guess that when I code, I just make sure that my comments are necessary.

For example, Eclipse gives a nice preview of methods and pulls in the javadoc into the tooltip when hovering over the comment. Therefore, I try to keep these up to date.

On the other hand, comments that just say the method name, or cannot be expected to be maintained, should not be created.

On the point of good code, yes you can write good code and reduce the need for comments, but there are just times when a comment is necessary. For example, there may be code for something that programmers (or humans in general) are not intuitively familiar with. Industry specific items in science, financials, etc. would qualify. If you ever expect a new person to come on and modify your code, you need to make sure they can jump in quickly. A quick comment as to what an industry specific item is, can go a long way to reducing the learning curve and allowing the contractor/new employee/etc to focus on what they are good at (coding).

Bitrot

[flyingfsck]

Comments suffer from incurable bitrot. So when I need to understand code, I never bother reading the comments, since it is usually more confusing than the code.

Re:Bitrot

[Jeremi]

Comments suffer from incurable bitrot.

It's curable -- all it takes is making sure that any time the code is changed, the associated comments are updated to match.

Of course, making sure that programmers actually do that is easier said than done, but the way to maximize the likelihood of that happening is to make sure the comments are as close to the code as possible -- preferably on the same line, or right above/below it. Comments that are off-screen (or worse, in a different file) when the code is modified are very unlikely to be updated in a timely manner.

Re:Bitrot

[nschubach]

It also relies on the coder trusting that the comment is accurate. Are you writing a program to do a specific task or writing comments to do that task? I put more faith in the code (because that's what the compiler runs) over the comment. If the comment says one thing and the code does something else, I'm willing to bet the code is more accurate. If I rewrite the code to match the comment, I may have just re-introduced an old bug. Now I have to go back through the file history to figure out if this was changed and/or if the original author was a poor commenter.

TFA sucks

[Sloppy]

As soon as I saw that the guy wrote "UX" I knew I was probably dealing with an exceptional moron (how that one acronym has turned into such a reliable red flag, I don't know, but look around and try to tell me it isn't true), but I still had no idea just how badly the article would go. It's not even stupid. It's just .. nothing.

The guy's argument is really that his text editor's preferences are/were set to something he doesn't like.

I shit you not. His editor's preferences were something he considers to be not-quite-right, and he noticed that it wasn't working well for him, and then somehow that turned into a programming article.

I can't even follow through on my "UX" prejudice and say "Aha! See? The guy knows nothing!" because he's taking it to the next level, so that from now on when I see "UX" it'll be "Aha, See? The guy says nothing." Although now that I think of it, maybe that's what the "UX" red flag has really always meant, all along. Hmm. Ok, you did give me something to think about.

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:All comments are lies.

[rastos1]

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

You mean something like this:

//
// Dear maintainer:
//
// Once you are done trying to 'optimize' this routine,
// and have realized what a terrible mistake that was,
// please increment the following counter as a warning
// to the next guy:
//
// total_hours_wasted_here = 42
//

?

My views

[Mr. McGibby]

From my blog:

http://madsoftware.blogspot.com/2007/06/my-confession.html

I have a confession to make. Forgive me. Wait, don't forgive me. I'm completely unapologetic. I am a programmer, and I don't write comments. I just needed to get that off my chest.

I don't believe in comments.

I have been writing a lot of fairly complex code lately. And all the while, the voices of dead Computer Science professors have been speaking to me. They repeat the mantra of good code commenting. I feel guilt, like when I go to church. Or when I don't make my bed in the morning. Of course, not one of them is able to give me any good suggestion of what a good set of comments is. They just tell me what isn't a good comment. So does that mean that anything else is a good comment? Like lots of swear words in the code. That's probably more useful than real comments, because they make me laugh and keep me from falling asleep at the keyboard.

Good comments, I'm told, are not just a rehash of what is already in the code. Well, if it isn't already in the code, then it isn't much use to the program is it? I don't believe in comments. I think they are mostly a waste of time. Maybe not for you, but for me they just make my life difficult. I have to make a context switch to English in order to write them. That takes time and just serves to confuse me.

Whenever I write English, I take the audience of my writing into account. Who is the audience for my comments? Some moron with a basic C++ book on his desk? Or the great man himself, Bjarne Stroustrup? Bjarne is pretty smart and will probably be able to figure out my code just fine without me, or my comments. Because he speaks C++. I speak C++ too, so that's how I like to communicate with computers and other people who speak the same language.

So I don't write comments. I'm one of those people who likes to use good variable names, good function names, and good file names. When I look at others' comments, I don't usually trust them, because they often don't make any sense. Or they are just plain wrong. That's just awesome. Like the time I first starting programming and I spent two days wondering why the second member of a pair of ints (pair) was always zero, even though the comments said it should contain some valuable piece of information. Actually, it was the first member, not the second one, which I finally figured out by actually looking at the damn code. Wonder of wonders, the code actually told me what the code did. Amazing.

I think that instead of comments we should put quotes of great authors at the top of all our code. That way, when people read our code, they will think that our code is profound, because we quote the greats of our time like, Dostoevsky, Helen Keller, or Dave Barry. And the best thing would be to just randomly pick those quotes so that when people try to make some connection between the code and the quote, they'll spend lots of time trying to figure out. Then they'll feel stupid, but won't want to admit it and we can fun of them when they can't explain the connection. And we won't have had to be smart at all, because all those people that we referred to are smart.

Have I even written comments? Of course, I slap all my comments in the headers, when I don't feel like writing documentation. Or when the function name is getting too long. Or when some fellow programmer makes me feel guilty for not following the religion of comments. What is the point of writing commments if the function name tells the whole story? Take vector for example, the size() function returns, guess what, the size of the vector. I know what you're thinking, that is completely non-intuitive. It's got to be commented. Look, if the function name can't tell you what the function does, then maybe you should change the function name. And if your function name gets too long, then maybe your function is doing too much.

Good, maintainable programs are easy to understand not because they hav

Re:My views

[Animats]

Transfer this guy to maintenance programing for a year.

Re:My views

[geekoid]

no thanks,. he will just put in a bunch of code he believes is obvious without taking into consideration any outside system the piece of code might be using.
Transfer him to McDonald's trainee.