10 best practices to follow while writing code comments

代码注释不要太多也不要太少，要适当。
首先要明白注释的目的是方便阅读者和维护(有个段子“写这段代码的时候，只有上帝和我知道它是干嘛的，现在只有上帝知道”)，如果你的代码写的足够清晰和简介，那么注释也可以精简
代码注释的作用之二在于写代码前先把步骤思路逻辑写成注释形式，然后在注释下写相应的代码，这也是一种好的做法
当然代码注释中你也能写一下让后来者很囧的话 sof1
代码更新对应的注释也要更新
注释里不要废话，get to the point(说重点)
注释是为了说明你为什么做而不是你做了什么
TODO和FIXME是必要的，但最好能进入bug追踪系统
ide工具自动生成的注释应该修改成具体，否则删除之
以下是代码注释的5个最佳实践：
1.注释不是副标题
2.注释不是艺术项目orz
3.注释块：滋扰或威胁？
4.注释不是代码控制
5.注释是代码的调味品
10个写注释的最佳实践
1.专注于代码的可读性，假设你不为你的代码注释，对变量，方法，类命名是确保其含义。
2.不要注释代码在做什么，代码本身就应该由类，方法，变量的命名来表达。
//calculates square root of given number 
//using Newton-Raphson method
public void abc(int a){
       r = a / 2;
       while ( abs( r - (a/r) ) > t ) {
       r = 0.5 * ( r + (a/r) );
       }
       System.out.println( "r = " + r );
}
修改如下：
public void squareRoot(int num){
       root = num/ 2;
       while ( abs(root - (num/ root) ) > t ) {
       r = 0.5 * (root + (num/ root));
       }
       System.out.println( " root = " + root );
}
3.注释只说明你为什么这么做，因为这些信息不明显。
4.如果在写类库，请用javadoc注释的样式
5.修改bug时带上JIRA等追踪系统的信息，这些系统里有bug的详细原因和描述
6.注释以简要为优，表达代码不能表达的信息
7.别在注释里写你联系信息，这些可以从svn/cvs的提交中查询到
8.在提交代码时也要添加注释
9.如果你想告知下一个开发人员知道某些信息，在类头部注释
10.最后，让你的同伴评审你的代码，看他是不是能看懂

有人说不需要注释，理由如下：
1) 别写注释，写更好的代码
2) Comments are an excuse, and you should only excuse something if you can't do it better. 
3) 设计模式或约定代替注释Rather than write comments, use a design pattern. Convention (design patterns) are far superior to excuses. 
4) If the business logic is so complex that it makes a small piece of code unreadable, it's a good time to add a comment.