I'm guessing that they were taught that code had to have comments and they were probably deducted points if they didn't have any. However, they weren't deducted points if they wrote bad comments and they weren't granted points if they wrote good comments. My guess is no one ever told them what the difference between a good comment and a bad comment was. So usually one of the first things I try to teach is what my guidelines for comments are.
- Meta data is a bad substitute for good readable code
- Write future proof comments. Don't write a summary comment that says what each step of your method will be. This is guaranteed to be out of date when someone else changes your method's code and forgets to update the comment. Now your comment is a lie.
- Tell me what your methods, properties, or objects will accomplish for me. Don't tell me how to use them. I can determine how best to use it once I understand what it does.
- Only current code matters, what the code did in the past is not important. Don't document history in your code files.
- Add line comments if the line is confusing or needs clarification. If it's clear on it's own, don't clutter it up with a comment.
- Break code into methods instead of using large or intricate commented sections.
- The shorter the better
- The goal is readable code
- Its better to read code than to read meta data
The main purpose of summary comments is to clarify what code is meant to accomplish when the name may not be sufficiently self explanatory. This will help people (including you) figure out how they should use that code. If they want to really understand what it does, they'll have to read it, but if the summary and name are written well enough they should understand enough to take advantage of its functionality.
The main purpose of line comments is to clarify code that may be harder to understand for some reason. This could be to describe why something is necessary (like a hack). Or to explain the effect a line will have on a line somewhere else (like to cause a loop to break).
There are cases where you may need to not follow these guidelines, that's why they're guidelines. However, in most cases they've served me well and helped me produce cleaner and more easily understood code.
This is more or less verbatum what we do at my work too.
ReplyDeleteI think in ~3 years ive put legitimate comments in maybe a dozen times and it was all to explain things that were complicated or confusing for some reason and no way to simplify them.
I dont know if i even like the concept of class or method header documentation. Think pre/post/etc.
Some languages (like ruby), or really communities still cling to it going so far as to write tools to generate documentation from inline comments (RDoc). Im up in the air on the value of this.