7.1 使用代码注释的目的
1. 文字说明代码的作用(即为什么要用编写该代码,而不是如何编写);
2. 确指出该代码的编写思路和逻辑方法;
3. 人们注意到代码中的重要转折点;
4. 使代码的阅读者不必在他们的头脑中仿真运行代码的执行方法.
7.2 编程原则
1. 用文字说明代码的作用:
简单的重复代码做写什么,这样的注释几乎不能给注释增加什么信息.如果你使用好的命名方法来创建直观明了的代码那么这些类型的注释绝对增加不了什么信息.
2. 如果你想违背好的编程原则,请说明为什么
有的时候你可能需要违背好的编程原则，或者使用了某些不正规的方法，.遇到这种情况时,请用内部注释来说明你在做什么和为什么要这样做。
技巧性特别高的代码段，一定要加详细的注释，不要让其他开发人员花很长时间来研究一个高技巧但不易理解的程序段。
3. 用注释来说明何时可能出错和为什么出错
4. 在编写代码前进行注释
给代码加注释的方法之一是在编写一个方法前首先写上注释.如果你愿意,可以编写完整句子的注释或伪代码.一旦你用注释对代码进行了概述,就可以在注释之间编写代码.
5. 在要注释的代码前书写注释
注释一定出现在要注释的程序段前，不要在某段程序后书写对这段程序的注释，先看到注释对程序的理解会有一定帮助。
如果有可能，请在注释行与上面代码间加一空行。
6. 纯色字符注释行只用于主要注释
注释中要分隔时，请使用一行空注释行来完成，不要使用纯色字符，以保持版面的整洁、清晰。
7. 避免形成注释框
用星号围成的注释框，右边的星号看起来很好,但它们给注释增加了任何信息吗?实际上这会给编写或编辑注释的人增加许多工作。
8. 增强注释的可读性
注释是供人阅读的，而不是让计算机阅读的。
1) 使用完整的语句。虽然不必将注释分成段落（最好也不要分成段落），但你应尽量将注释写成完整的句子。
2) 避免使用缩写。缩写常使注释更难阅读，人们常用不同的方法对相同的单词进行缩写，这会造成许多混乱，如果必须对词汇缩写，必须做到统一。
3) 将整个单词大写，以突出它们的重要性。若要使人们注意注释中的一个或多个单词，请全部使用大写字母。
9. 对注释进行缩进，使之与后随的语句对齐。
注释通常位于它们要说明的代码的前面。为了从视觉上突出注释与它的代码之间的关系，请将注释缩进，使之与代码处于同一个层次上。
10. 为每个方法赋予一个注释标头
每个方法都应有一个注释标头。方法的注释标头可包含多个文字项，比如输入参数、返回值、原始作者、最后编辑该方法的程序员、上次修改日期、版权信息。
11. 当行尾注释用在上面这种代码段结构中时，它们会使代码更难阅读。
使用多个行尾注释时（比如用于方法顶部的多个变量说明），应使它们互相对齐。这可使它们稍容易阅读一些。
12. 何时书写注释
1) 请在每个if语句的前面加上注释。
2) 在每个switch语句的前面加上注释。与if语句一样，switch语句用于评估对程序执行产生影响的表达式。
3) 在每个循环的前面加上注释。每个循环都有它的作用，许多情况下这个作用不清楚直观。
7.3 注释那些部分
项目 | 注释哪些部分 |
实参/ 参数 | 参数类型 参数用来做什么 任何约束或前提条件 示例 |
字段/ 字段/属性 | 字段描述 注释所有使用的不变量 示例 并行事件 可见性决策 |
类 | 类的目的 已知的问题 类的开发/维护历史 注释出采用的不变量 并行策略 |
编译单元 | 每一个类/类内定义的接口，含简单的说明 文件名和/或标识信息 版权信息 |
接口 | 目的 它应如何被使用以及如何不被使用 |
局部变量 | 用处/目的 |
成员函数注释 | 成员函数做什么以及它为什么做这个 哪些参数必须传递给一个成员函数 成员函数返回什么 已知的问题 任何由某个成员函数抛出的异常 可见性决策 成员函数是如何改变对象的 包含任何修改代码的历史 如何在适当情况下调用成员函数的例子适用的前提条件和后置条件 |
成员函数内部注释 | 控制结构 代码做了些什么以及为什么这样做 局部变量 难或复杂的代码 处理顺序 |
7.4 示例
7.4.1 块注释：
主要用来描述文件，类，方法，算法等。一般用在文档和方法的前面，也可以放在文档的任何地方。以‘/*’开头，‘*/’结尾。例：
……
/*
* 注释
*/
……
7.4.2 行注释：
主要用在方法内部，对代码，变量，流程等进行说明。与块注释格式相似，但是整个注释占据一行。例：
……
/* 注释 */
……
7.4.3 尾随注释：
与行注释功能相似，放在代码的同行，但是要与代码之间有足够的空间，便于分清。例：
int m=4 ; /* 注释 */
如果一个程序块内有多个尾随注释，每个注释的缩进应该保持一致。
7.4.4 行尾注释：
与行注释功能相似，放在每行的最后，或者占据一行。以‘//’开头。
7.4.5 文档注释：
与块注释相似，但是可以被javadoc处理，生成HTML文件。以‘/**’开头，‘*/’结尾。文档注释不能放在方法或程序块内。例：
/**
注释
*/
8. 表达式和语句
8.1 每行应该只有一条语句。
8.2 if-else,if-elseif语句，任何情况下，都应该有“{”，“}”，格式如下：
if (condition) {
statements;
} else if (condition) {
statements;
} else{
statements;
}
8.3 for语句格式如下：
for (initialization; condition; update) {
statements;
}
如果语句为空：
for (initialization; condition; update) ;
8.4 while语句格式如下：
while (condition) {
statements;
}
如果语句为空:
while (condition);
8.5 do-while语句格式如下：
do {
statements;
} while (condition);
8.6 switch语句，每个switch里都应包含default子语句,格式如下：
switch (condition) {
case ABC:
statements;
/* falls through */
case DEF:
statements;
break;
case XYZ:
statements;
break;
default:
statements;
break;
}
8.7 try-catch语句格式如下：
try {
statements;
} catch (ExceptionClass e) {
statements;
} finally {
statements;
}
9. 错误处理和异常事件
通常的思想是只对错误采用异常处理：逻辑和编程错误，设置错误，被破坏的数据，资源耗尽，等等。
通常的法则是系统在正常状态下以及无重载和硬件失效状态下，不应产生任何异常。异常处理时可以采用适当的日志机制来报告异常，包括异常发生的时刻。不要使用异常实现来控制程序流程结构。
10. 封装、事务
1. 非商务公用组件单独封装
2. 每一个业务流程单独封装
3. 一次方法（组件）的调用应能完成某一项功能或流程，即符合完整性
4. 一次方法（组件）的调用符合ACID事务性
5. 多次方法（组件）的调用应包含在一个事务中
11. 可移植性
1. 尽量不要使用已经被标为不赞成使用的类或方法。
2. 如果需要换行的话，尽量用 println 来代替在字符串中使用"/n"。
3. 用separator()方法代替路径中的”/”或”/” 。
4. 用pathSeptarator()方法代替路径中的 ” : ” 或 ” ;” 。
