Chinaunix首页 | 论坛 | 博客
  • 博客访问: 220880
  • 博文数量: 136
  • 博客积分: 2919
  • 博客等级: 少校
  • 技术积分: 1299
  • 用 户 组: 普通用户
  • 注册时间: 2011-03-11 09:08
文章分类

全部博文(136)

文章存档

2013年(1)

2011年(135)

我的朋友

分类: Java

2011-03-31 10:34:55

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
  1. i++;//increment i
Another example is a javadoc that says nothing more than (or even less than) the function signature:
  1. /**
  2.   * @param sellRequest
  3.   * @return
  4.   * @throws ManagedComponentException
  5.   */
  6. public SellResponse beginSellItem(SellRequest sellRequest)
  7. throws ManagedComponentException
Comments should say things that the code cannot say for itself.

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
阅读(522) | 评论(0) | 转发(0) |
给主人留下些什么吧!~~