Clean Code— A Handbook of Agile Software Craftsmanship
Robert C. Martin. Pearson Education
Smells and Heuristics
Comments
C1: Inappropriate Information
It is inappropriate for a comment to hold better held in a different kind of system such as your source code control system, your issue tracking system, or any other record-keeping system.
In gerenal, meta-data such as authors, lastmodified-date, SPR number, and so on should not appear in comments.
comments should be reserved for technical notes about the code and design.
C2: Obsolete Comment
A comment that has gotten old, irrelevant, and incorrect is obsolete.
It is best not to write a comment that will become obsolete. If you find an obsolete comment, it is best to update it or get rid of it as quickly as possible. Obsolete comments tend to migrate away from the code they once described. They become floating islands of irrelevance and misdirection in the code.
C3: Redundant Comment
A comment is redundant if it describes something that adequately describes itself. For example
Another example is a javadoc that says nothing more than (or even less than) the function signature:
- /**
-
* @param sellRequest
-
* @return
-
* @throws ManagedComponentException
-
*/
-
public SellResponse beginSellItem(SellRequest sellRequest)
-
throws ManagedComponentException
C4: Poorly Written Comment
A comment worth writing is worth writing well. If you are going to write a comment, take the time to make sure it is the best comment you can write. Choose your words carefully. Use correct grammar and punctuation. Don't ramble. Don't state the obvious. Be brief.
C5: Commented-Out Code
When you see commented-out code, delete it! Don't worry, the source code control system still remembers it. If anyone really needs it, he or she can go back and check out a previous version. Don't suffer commented-out code to survive.
Date: 2011-03-31 11:00:02 EDT
HTML generated by org-mode 7.4 in emacs 23
阅读(530) | 评论(0) | 转发(0) |
