白盒测试 [代码规范][Java] 二

转载自：http://blog.sina.com.cn/s/articlelist_1154237180_1_1.html

3. 注释规范

3.1 注释 vs 代码

• 注释宜少二精，不宜多而滥，更不能误导
• 命名达意，结构清晰， 类和方法等责任明确，往往不需要，或者只需要很少注释，就可以让人读懂；相反，代码混乱，再多的注释都不能弥补。所以，应当先在代码本身下功夫。
• 不能正确表达代码意义的注释，只会损害代码的可读性。
• 过于详细的注释，对显而易见的代码添加的注释，罗嗦的注释，还不如不写

  。

• 注释要和代码同步，过多的注释会成为开发的负担
• 注释不是用来管理代码版本的，如果有代码不要了，直接删除，svn会有记录的，不要注释掉，否则以后没人知道那段注释掉的代码该不该删除。

3.2 Java Doc

表明类、域和方法等的意义和用法等的注释，要以javadoc的方式来写。Java Doc是个类的使用者来看的，主要介绍 是什么，怎么用等信息。凡是类的使用者需要知道，都要用Java Doc 来写。非Java Doc的注释，往往是个代码的维护者看的，着重告述读者为什么这样写，如何修改，注意什么问题等。 如下：

public class TestClass { public String name;   public void call() {   } }

3.3 块级别注释

3.3.1 块级别注释，单行时用 //, 多行时用 。

3.3.2 较短的代码块用空行表示注释作用域

3.3.3 较长的代码块要用

和

包围
如：

//取得dao OrderDao dao = Factory.getDao("OrderDao");   Order order =dao.findById(456);   //更新订单 order.setUserName("uu"); order.setPassword("pass");order.setPrice("ddd");   orderDao.save(order);

3.3.4 可以考虑使用大括号来表示注释范围

使用大括号表示注释作用范围的例子：

{ //取得dao OrderDao dao = Factory.getDao("OrderDao");   Order order =dao.findById(456);   //更新订单 order.setUserName("uu"); order.setPassword("pass");order.setPrice("ddd");   orderDao.save(order); }

3.4 行内注释

行内注释用 // 写在行尾

4 最佳实践和禁忌

4.1 每次保存的时候，都让你的代码是最美的

程序员都是懒惰的，不要想着等我完成了功能，再来优化代码的格式和结构，等真的把功能完成，很少有人会再愿意回头调整代码。

4.2 使用log而不是System.out.println()

log可以设定级别，可以控制输出到哪里，容易区分是在代码的什么地方打印的，而System.out.print则不行。而且，System.out.print的速度很慢。所以，除非是有意的，否则，都要用log。至少在提交到svn之前把System.out.print换成log。

4.3 每个if while for等语句，都不要省略大括号{}

看下面的代码：

if (a > b) a++;

如果在以后维护的时候，需要在a > b 时，把b++，一步小心就会写成：

if (a > b) a++; b++;

这样就错了，因为无论a和b是什么关系，b++都会执行。 如果一开始就这样写：

if (a > b) { a++; }

相信没有哪个笨蛋会把b++添加错的。而且，这个大括号使作用范围更明显，尤其是后面那行很长要折行时。

4.4 善用TODO:

在代码中加入 //TODO: ，大部分的ide都会帮你提示，让你知道你还有什么事没有做。比如：

if (order.isPaid()) { //TODO: 更新订单 }

4.5 在需要留空的地方放一个空语句或注释，告述读者，你是故意的

比如：

if (!exists(order)) { ; }

或：

if (!exists(order)) { //nothing to do }

4.6 不要再对boolean值做true false判断

比如：

if (order.isPaid() == true) { // Do something here }

不如写成：

if (order.isPaid()) { //Do something here }

后者读起来就很是 if order is paid, …. 要比 if order’s isPaid method returns true, … 更容易理解

4.7 减少代码嵌套层次

代码嵌套层次达3层以上时，一般人理解起来都会困难。下面的代码是一个简单的例子：

public void demo(int a, int b, int c) { if (a > b) { if (b > c) { doJobA(); } else if(b < c) { doJobB() } } else { if (b > c) { if (a < c) { doJobC(); } } } }

减少嵌套的方法有很多：

• 合并条件
• 利用 return 以省略后面的else
• 利用子方法

比如上例，合并条件后成为：

public void demo(int a, int b, int c) { if (a > b && b > c) { doJobA(); } if (a > b &&c > b) { doJobB(); } if (a <= b && c < b && a < c) { doJobC(); } }

如果利用return 则成为：

public void demo(int a, int b, int c) { if (a > b) { if (b > c) { doJobA(); return; }doJobB() return; }   if (b > c) { if (a < c) { doJobC(); } } }

利用子方法，就是将嵌套的程序提取出来放到另外的方法里。

4.8 程序职责单一

关注点分离是软件开发的真理。人类自所以能够完成复杂的工作，就是因为人类能够将工作分解到较小级别的任务上，在做每个任务时关注更少的东西。让程序单元的职责单一，可以使你在编写这段程序时关注更少的东西，从而降低难度，减少出错。

4.9 变量的声明，初始化和被使用尽量放到一起

比方说如下代码：

int orderNum= getOrderNum();   //do something withou orderNum here   call(orderNum);

上例中的注释处代表了一段和orderNum不相关的代码。orderNum的声明和初始化离被使用的地方相隔了很多行的代码，这样做不好，不如这样：

//do something withou orderNum here   int orderNum= getOrderNum(); call(orderNum);

4.10 缩小变量的作用域

能用局部变量的，不要使用实例变量，能用实例变量的，不要使用类变量。变量的生存期越短，以为着它被误用的机会越小，同一时刻程序员要关注的变量的状态越少。实例变量和类变量默认都不是线程安全的，局部变量是线程安全的。比如如下代码：

public class OrderPayAction{ private Order order;   public void doAction() { order =orderDao.findOrder(); doJob1(); doJob2(); }   private void doJob1() {doSomething(order); }   private void doJob2() { doOtherThing(order); } }

上例中order只不过担当了在方法间传递参数之用，用下面的方法更好：

public class OrderPayAction{   public void doAction() { order = orderDao.findOrder();doJob1(order); doJob2(order); }   private void doJob1(Order order) {doSomething(order); }   private void doJob2(Order order) { doOtherThing(order); } }

4.11 尽量不要用参数来带回方法运算结果

比如：

public void calculate(Order order) { int result = 0; //do lots of computing and store it in the result   order.setResult(result); }   public void action() { order =orderDao.findOrder(); calculate(order);   // do lots of things about order }

例子中calculate方法通过传入的order对象来存储结果， 不如如下写：

public int calculate(Order order) { int result = 0; //do lots of computing and store it in the result   return result; }   public void action() { order =orderDao.findOrder(); order.setResult(calculate(order));   // do lots of things about order }