Comments On Code Comments? 472
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?"
Use vi (Score:3, Insightful)
Use vi. Always works for me.
Good comments are good. (Score:5, Insightful)
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.
Re:Doesn't matter in the end (Score:5, Insightful)
if you can't fit the documentation into your method (and variable names), that method is likely too long and complicated.
Removing comments from code (Score:5, Insightful)
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:Doesn't matter in the end (Score:5, Insightful)
Re:Save time (Score:5, Insightful)
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:
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:Doesn't matter in the end (Score:5, Insightful)
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:
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 (Score:5, Insightful)
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.
Bitrot (Score:3, Insightful)
Re:Doesn't matter in the end (Score:5, Insightful)
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 (Score:5, Insightful)
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:Write clear code, remove comments (Score:5, Insightful)
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:Doesn't matter in the end (Score:2, Insightful)
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 (Score:5, Insightful)
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 (Score:4, Insightful)
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 (Score:5, Insightful)
Re:Doesn't matter in the end (Score:4, Insightful)
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 (Score:5, Insightful)
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 (Score:5, Insightful)
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:
Bonus points if it's pre/proceeded by a complex block of uncommented, impeneterable code.
Re:Doesn't matter in the end (Score:5, Insightful)
int GetNumberOfUsers(int category_id, int country_id, int company_id)
{
int num_users=0;
DBConnection db=new DatabaseConnection('central_database');
if(db==null){explode();}
db->Close();
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;
x=sqrt(sin(log(y)/pi)*e);// this is the lambert/highlander formula
x=lookup_table[y];
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 (Score:2, Insightful)
Until the resource no longer exists.
Re:Doesn't matter in the end (Score:5, Insightful)
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