This thought/rant recently arose whilst editing a large program.
How much trust should you have in comments?
The problem I had was easy to fix, but the code it was in had been copied from elsewhere along with embedded comments that no longer applied. So I spent a quiet half hour checking out comments throughout the code, only to find that the most applicable one was right at the start, describing the programs functionality (and even that was wrong - parameters in/out etc).
The 'cut and paste' culture of the development has spread inaccurate or irrelevant comments over the whole system, to the point now that they can/should be ignored. Descriptive naming of fields and functions will normally provide a far better clue as to the functionality than these comments.
It wouldn't be too bad but I've seen this happen time and again across lots of different development teams (and no doubt been responsible for a few as well). Problems arise when you pick up a piece of code to fix/change part of it. Following the logic flow is easy enough (usually), but for the most part that requires reading the code - not the comments.
And so this leads me to 4 levels of generalisation:
1. The code does exactly what the comment say's it does so look elsewhere for your bug.
Good: Can skip through a routine quickly to the appropriate parts. Bad: Some very large assumptions are made.
2. Comments are there to help if the code, or the reason for the code isn't obvious.
Good: You can ignore comments around most of the 'obvious' code. Bad: Still relying on them for difficult code.
3. Comments should be treated as a work of fiction until proved otherwise.
Good: Might give you a hint - but you'll still have to read the code to check it. Bad: Now you have to read the code and a description.
4. Comments are the work of the devil, put there to fool you. Ignore them at every turn and rely solely on code.
Good: You'll always know exactly what's going on. Bad: May take a long time when the description was right under your nose.
Breath in for 10, hold for 10, and breath out for 10.
Now I've calmed down about that, I'd like to share my thoughts on dealing with the little rascals.
The only sensible approach that I've found is to apply each rule in turn and to treat comments as if they are code. Fix the broken ones, only put them in when it's necessary, and remove redundant ones. Oh, and to only apply these rules to the areas of code that I touch.
Remember - Comments are for life, not just Christmas.
Thanks for letting me get that off my chest.
'I think the problem lies in the fact that your data doesn't fit my program'.
edited: Wed Apr 23 13:58:30 2003 by jeffa - added readmore tag
In reply to No Comment by awkmonk
| For: | Use: | ||
| & | & | ||
| < | < | ||
| > | > | ||
| [ | [ | ||
| ] | ] |