I remember my C++ teacher arguing strongly that all code should be commented and you should never hesitate to add comments. "When in doubt: comment!". I did not agree with him then, and I do not agree with him now. With experience, I have come to realize that comments in high level language code is rarely needed. I won't go so far as to say that writing comments are a failure, but its pretty close.
Readable code is self-documenting code!
A comment followed by a block of code can often be replaced by a method which states the intent just as well as the comment, and makes the code more modular and reusable.
- It makes refactoring happen more often.
- It helps us write readable code. Readable code is a joy to work with.
- It tends to make methods short and sweet.
- It avoids comments getting out of sync with the code
- It challenges you to rewrite commented code that is hard to understand.
Apart from the cleanliness of the code, there are a number of others problem with having comments in the code as well. Number one problem being that comments does not automatically change with the code. You end up with comments that disagrees with the actual program, which leads you on a wild goose chase spending lots of energy trying to figure out what is going on. I rarely read in-line comments for this reason and when I do, I always have to assume they are wrong.
Note that I am talking about in-line comments primarily. There are situations where comments have its uses. For example, to provide an overview of a class or module, to reference external documentation or maybe to explain the rationale for a workaround in the code.
When I see comments in code, I think of them as personal challenges:
Can I remove that comment and make the code more readable?
Try it yourself next time!
int d; // elapsed time in days
Remove the comment and make the code obvious instead:
int elapsedTimeInDays;
// If the user should be allowed access to the admin page
if ((user.status && U_LGD_IN
&& user.login_time < 3600
&& user.access || U_ADMIN))
Replace the comment with a new method which encapsulates the logic:
if (user.isAllowedAccessTo(Pages.ADMIN))
/**
* BasicCtrl constructor.
*/
public BasicCtrl() {
super();
}
You don't say? It is safe to assume that readers know the basics of the language they are reading.
/**
* Description:
* @param
* @return
* @exception
* @return java.lang.String
* @param action java.lang.String
*/
public String createCustomer(String action) {
Huh? Remove comments that doesn't say anything useful. Methods may be commented if they are in a public api or if their use is not obvious. Disable auto-generation of comments in your editor.
//----------------------------------------------------------
// Execute the statement
//----------------------------------------------------------
statement.execute();
That comment is stating the obvious. Remove it. Also, don't get fancy with ascii art.
// TODO: these are not needed!
... code ...
Don't let todos linger in the code, fix them instead. Writing a todo is just a lazy way to avoid dealing with a problem.
The comments that should live in code are comments that tell why code does what it does. We can tell what it does, but the backstory of the reasons for it is what is often lost to folklore.
ReplyDelete// Status X users no longer allowed to perform whatzis
// See ticket #4914
Comments don't just say what the code does. They also say why you chose to do it that way.
ReplyDeleteI usually write javadoc style comments (in PHP) so that my editor will handle autocomplete and parameter hinting. So not completely useless :)
ReplyDelete