Slashdot Mirror
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?"
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.
if you can't fit the documentation into your method (and variable names), that method is likely too long and complicated.
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.
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.
I'm old enough to remember when discussions on Slashdot were well informed.
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.
I am officially gone from
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.
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.)