Just now I realized some of my more recent code has more comments than actual code.. Is that a good thing or a bad thing? I am growing old and is it time to shoot me while I still haven't looked into .NET yet??
When I'm reading other peoples code I generally like comments that explain non-obvious algorithms, or places where the author hit a snag or bug and is alerting future maintainers.
I generally don't like comments that explain obvious or trivial code.
I like to revisit my code after a couple of months and see if the comments still make sense. Lots of times I end up stripping them out or re-writing them.
-- Douglas HunterBad, if you ask me.
Structuring code well, choosing identifiers carefully, and using whitespace generously makes code mostly self-explanatory. The reason why the code is there and how to use it should be documentation. Comments are for explaining non-obvious algorithms, for calling attention to lurking bugs, or other problems, and the like.
Basically, the documentation should explain why the code is there, and the code should explain how it works. Comments are only for highlighting surprising points in the code.
Obviously, the fewer surprising points, the better.
Re:
Beatnik on 2005-07-15T07:18:16
There are large chunks refering to other documentation, changelogs and technical requirements. There are also the sections not explaining how the code works but why it is done like it is..Re:
mary.poppins on 2005-07-17T22:17:12
"There are also the sections not explaining how the code works but why it is done like it is.. "
The key to good comments is to explain why, not how. Kudos. As previously mentioned, good code makes the "how" clear.
