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

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

Save time

[bill_mcgonigle]

Comment first, fill in the code later.

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:Doesn't matter in the end

[devent]

No, that is for what tests are. Tests and a Version Control System for the old approaches.

You implement a solution, then you experience a bug for which you write a test case. Then you re-write your solution so the test passes. No need to write any comments, you have a test that documents the bug. Also in the future if you re-write the solution again, you are sure that you will not experience the same bug again.

Of course that approach means you have actually write a test and fix the bug. More easily is of course to write a comment like "Don't touch that, it's a corner case Foo that I experienced in 1988".

My opinion on hide or collapse stuff is very easy: it's a bad idea. Sooner or later developers will hide a lot of stuff, code, comments, it's like why it is a bad idea to hide stuff under the carped: clean up your room and not hide the dirt under the carpet.

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

[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

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