Writing Clear Code－－整洁的Java代码编写规范

Writing Clear Code

译自：

Aug 17, 2011

编码的总体目标是使其易读和易于理解，风格良好的程序易于调试，维护，且错误少。编码与撰写文章十分相似，当我们写一篇文章时，如果文章具有正确的语法和标点，你所要表达的内容更具有说服力。当编写程序时，你也应当遵守同样的原则，尤其是当你的程序代码由其他人负责维护和长期使用时，这条原则显得更加重要。当你需要理解和维护他人的代码时，更能体会到代码具有良好风格的重要性！

1. 编码原则

• 保持程序和方法的短小和易管理
• 尽量使用编程语言特有的习惯用法
• 尽量采用简单的逻辑和控制流程
• 避免使用magic数，为其赋以有意义的名称
  

2. 命名规则－为变量， 方法和类命名规则如下：
(1) 尽量采用能够表达变量意图的名称， 选取那些易于发音的名称，同时避免使用缩写词。例如，采用(2) wagePerHour或hourlyWage 代替 wph；采用 polygon 代替 p 或 poly 或 pgon.
(2) 保持一致性。
(3) 命名boolean变量和方法要避免二义性, 如 isPrime 或 isEmpty() 或 contains().
(4) 命名短生命周期变量和循环变量时采用短名称(如i,j), 重要的变量采用更具有描述性的名称.
(5)避免采用通用的名字如foo, tmp 和无意义的名字如 fred.尽可能的采用应用领域中的术语命名.
(6)根据常量的意义命名,而不是根据常量值, 如 用DAYS_PER_WEEK 代替 SEVEN.

标识符及命名规则：                       
（1） 变量：短小, 有意义, 名字为程序读者提供变量的意义,而不是如何使用. 采用以小写字母开头,大小写混合形式命名变量. 示例: mass, hourlyWage, isPrime
（2) 常量:采用大写形式,　中间单词采用下划线分隔. 示例:　N, BOLTZMANN, MAX_HEIGHT
(3) 类:　采用名词表明类的意义,　以大写字母开头,大小写形式命名类名. 示例:class Complex, class Charge, class PhoneNumber
(4) 方法: 采用动词表明方法做什么.采用小写字母开头,大小写混合形式命名类. 示例:move(), draw(), enQueue()

3. 注释
程序员采用注释来解释程序,帮助读者理解程序如何工作及如何实现.作为一条通用规则,代码告诉计算机和程序员程序做什么;注释告诉程序员程序为什么这样做.注释可以出现在程序的任何空白处, Java编译器忽略注释.
(1)行注释.行注释以 // 开头, 直到行尾, // 到行尾之间的文本都被忽略.
(2)块注释.块注释以 /* 开头, 以*/结束, /* 和*/ 之间的文本都被忽略.
(3)Bold 注释.一种特殊形式块注释, 用于提醒读者注意:

/* -------------------------------------------------------
 * Here is a block comment that draws attention to itself.
 *-------------------------------------------------------*/

(4) Javadoc 注释. 一种特殊形式块注释, 以 /** 开头, 主要用于自动生成类的API描述.
(5) 保证注释与代码的一致性, 更新代码时确保同时更新注释.
(6) 注释不要重复代码, 记住, 注释应当描述程序做什么和为什么做, 而不是如何做.
     

    i++; // increment i by 1

(7) 注释掉所有让人困惑的代码,最好是重写代码.
(8) 为你的程序加入bold 注释, 说明作者，日期，程序的目的，如何执行程序。

/*----------------------------------------------------------------
 *  Author:        Kevin Wayne
 *  Written:       5/3/1997
 *  Last updated:  8/7/2006
 *
 *  Compilation:   javac HelloWorld.java
 *  Execution:     java HelloWorld
 *
 *  Prints "Hello, World". By tradition, this is everyone's
 *  first program.
 *
 *  % java HelloWorld
 *  Hello, World
 *
 *----------------------------------------------------------------*/

(9) 为所有重要的变量名称添加注释(包括实例变量), 并垂直排列注释.

private double rx, ry;    //  position
private double q;

10) 为所有方法添加注释说明该方法做什么, 包括方法的输入,输出及作用side effects, 注释中引用参数名称.

/**
 *   Rearranges the elements in the array a[] in random order
 *   using Knuth's shuffling algorithm.
 *
 *   Throws a NullPointerException if a is null.
 */
public static void shuffle(String[] a)

4. 空格符(Whitespace). 程序员在编码时使用空格符以提高代码易读性.
(1) 每行只写一条语句.
(2) 采用空行将代码分隔成多个逻辑部分.
(3) 在二元操作符(e.g., <=, = +)和操作数之间加入空格, 但在强调优先顺序时可以不加空格.

a*x + b

(4) 在关键词(e.g., while, for, if)和其后跟括号之间加入空格.
(5) 在for 循环中在每一条语句后加入空格.
   for(int i=0;i(6) 参数列表中在每个逗号后加入空格.
(7) 在注释符后加入空格.

//This coment has no space
//after the delimiter and is
//difficult to read.

//   This comment has two
//  spaces after the delimiter

(8) 分号前不加空格.
(9) 对象名,分隔符.和方法名之间不加空格.
(10) 方法名和其左括号之间不加空格.
(11) 相关代码通过加入空行进行分组来提高可读性.
(12) 采用空格符并排代码来提高可读性.

int N          = Integer.parseInt(args[0]);  //  size of population
int trials = Integer.parseInt(args[1]); // number of trials

5. 缩进(Indenting). 程序员采用格式和缩进代码来展示代码结构, 类似于提纲(outline)的使用.
(1) 每行代码不超过80个字符.
(2) 每行只写一条语句.
(3) 缩进一致的空格符, 推荐3或4个空格.
(4) 使用空格符而不用tab符. 现代IDEs在键入tab键时插入空格符(称为 soft tabs). Hard tabs 己经过时了, 早些时候用于数据压缩.
(5) 程序中嵌套的每一层使用一个新的缩进.
(6) 采用K&R 或 BSD/Allman 缩进风格, 并保持一致性.

/  K&R style indenting
public static void  main(String[] args) {
    System.out.println("Hello, World");
}

//  BSD-Allman style indenting
public static void main(String[] args)
{
    System.out.println("Hello, World");
}

Q + A

Q. Are there any official coding standards?

A. Here are Sun's Code Conventions for the Java Programming Language.

Q. Any good references on programming style?

A. The Practice of Programming by Brian W. Kernighan and Rob Pike is a classic.