代码注释最佳实践

代码注释及格式化关乎代码的可读性，而代码可读性对于代码可维护性又是至关重要的，因此一些编程的小细节有助于提高代码可维护性。本文列举了一些代码注释及格式化的优秀示例。



一、注释



注释是代码的一部分，其重要性显而易见。缺少注释的代码可以说是没有用的，虽然有人建议使用自文档化代码，不过我们认为自文档化+代码文档是最好的。



1. 只在必要时使用注释



也就是说不需要对每一行都使用注释

int count = 0; // 将count的初始值赋为0(?!?)

但缺少注释会增加维护难度，所以变量、方法的命名应该易于理解

int s = sqrt(v1) + v2 / v3 + fread(s). getChar(0)  //(?!?)
List<int> getVal(int val, int len, String op) //(?!?)

2. 错误的注释还不如没有注释，应尽量避免。



3. 为重要的且没有自文档化的变量写注释。



4. 为公开的方法写注释（例如JavaDoc declaration），当然，这些注释应该是真的有必要添加的。



5. 类似“了解”、“待办”的注释也许对当天来说很重要，但之后应该删除。



二、格式化



有很多开发工具（如maven checkstyle）都提供代码格式化的功能，且格式化操作可在代码保存时自动进行，但这些格式不一定符合公司的格式规则，因此在使用之前要对其进行设置。



1. 使用一致的括号格式。括号一般都加在当前行的尾部或新一行的首部，选择一种添加方式，并在所有代码行中保持相同的格式。



2. 使用一致的空行。空行用于分隔代码和语义组，提高代码可读性。例如使用3行空行来表示方法的结束，没有空行或每行代码间都加空行却不利于代码美观。



3. 留意首行缩进。正确的缩进对于语义块来说就像括号和空行一样重要。



4. 限制每行的字符数，提高可读性。大多数程序员认可的限制数为80个左右。



5. 使用一致的空格，通常以下的这些情况要使用空格：

//运算符和变量之间 
a += b , c = 0; (a == b)

//语句关键字和括号之间
if (value) {, public class A { 

//循环的“；”号后
for (int i = 0; i < length; i++) 

//类型和变量之间
(int) value , (String) value

英文原文：10 Best Practices for Code Commenting & Formatting 

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.