JAVA编程规范（下）
2016-03-27
6. 代码的格式化
6.1 对代码进行格式化时，要达到的目的
1. 通过代码分割成功能块和便于理解的代码段，使代码更容易阅读和理解；
2. 使用空行和注释行，将程序中逻辑上不相关的代码块分开。比如：变量声明部分和代码语句间的分隔；较长的方法中，完成不同功能的代码块间的分隔。要避免出现逻辑上混乱的分隔，如：某一逻辑功能代码块中间用空行进行了分隔，但是在相邻功能代码块之间却没有分隔，这样会给程序阅读者造成错觉。
3. 减少为理解代码结构而需要做的工作；
4. 使代码的阅读者不必进行假设；
5. 使代码结构尽可能做到格式清楚明了。
6.2 编程原则
1. 要将多个语句放在同一行上
不论是变量声明，还是语句都不要在一行上书写多个。
2. 缩进后续行
当你将变量设置为某个值时，所有后续行的缩进位置应与第一行的变量值相同；
当你调用一个方法时，后续行缩进到第一个参数的开始处；
当你将变量或属性设置为等于表达式的计算结果时，请从后面分割该语句，以确保该表达式尽可能放在同一行上。
3. 在if语句后缩进；
在else语句后缩进
在switch语句后缩进
在case语句后缩进
在do句后缩进
已经用行接续符分割的语句的各个行要缩进
对从属于行标注的代码进行缩进。
4. 在执行统一任务的各个语句组之间插入一个空行。好的代码应由按逻辑顺序排列的进程或相关语句组构成。
7. 代码的注释
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文件。以‘/**’开头，‘*/’结尾。文档注释不能放在方法或程序块内。例：
/**
多行注释
*/
2016-03-27
CHARLIEPAN