文档介绍：.
23 / 24
软件开发编码规范说明

梁峰 2017-5-31
2017
一、高级语言2

"动词", 第一个字母是小写,但是中间单词的第一个字母是大写。如果是返回一个成员变量的值,名称一般为get+成员变量名,如若返回的值是bool变量,一般以is作为前缀。如果是修改一个成员变量的值,名称一般为：set + 成员变量名。函数或方法名的长度不得少于8个字母。
文件命名
文件的名字应该使用名词。每个单词第一个字母须大写。文件的命名应该尽量用英文表达出文件的内容。避免使用单词的缩写,除非它的缩写已经广为人知,如HTTP。文件的名字中应能反映出文件的类型〔针对不同的编程语言,有不同类型的文件。要求文件名的长度不得少于5个字母。对于文件中类的命名,前缀用大写字母J,后跟类的功能,中间单词第一个字母要大写。
注释
代码注释
注释将增加代码的清晰度。注释需简洁、明了,含义准确,防止注释二义性,避免在注释中使用缩写,特别是非常用缩写。注释不允许包括其他的特殊字符。可以先写注释,后写代码,但对代码的注释不可放在代码下面,须放在代码上方或右方相邻位置。
.
6 / 31
变量注释
对于变量的注释必须紧跟在变量的后面说明变量的作用。对于所有有物理含义的变量、常量、数据结构声明<包括数组、结构、类、枚举等>,如果其命名不是充分自注释的,在声明时都必须加以注释,说明其物理含义。原则上对于每个变量都应该注释,但对于意义非常明显的变量,可以不注释。
对于全局变量必须有较详细的注释,包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等进行说明。
函数注释
对于函数,须在函数头部从函数的目的、功能、输入参数、输出参数、返回值、调用关系〔函数、表、"算法"、"日期"等方面进行注释。不允许在一行代码或表达式的中间插入注释。在定义函数原型时,须对每一个参数加以注释。
对于函数体内的分支语句〔条件分支、循环语句等必须编写注释,对于前后顺序不能颠倒的情况,建议在注释中增加序号。对于从一个case子句进入后续的case子句,须用注释" Fall through"明确标记。当代码段较长,特别是多重嵌套时,这样做可以使代码更清晰,更便于阅读。
如果部分代码不再使用,但还要保存,须使用#if UNUSED标识。如果部分代码目前不能使用,但最后肯定要用,须使用#if LATER标识。使用"TODO: comment"标记未完成代码," BUG: comment"标记错误代码。
.
8 / 31
文件注释
每个源文件有效注释量必须占代码量的20％以上。必须在每个源文件的头部进行注释,注释须包含：版权说明、版本号、生成日期、作者、主要函数及其功能的简要说明、与其它文件的关系、修改日志〔说明对文件的修改内容、修改原因以及修改日期。
修改代码的同时必须修改相应的注释,以保证注释与代码的一致性。不再有用的注释要删除。
错误和异常处理
错误处理
系统在正常状态下以及无重载和硬件失效状态下,不应产生任何异常。发生异常或错误时,对于应用服务层不允许抛出异常中断服务程序的运行,须由系统自行处理保持程序正常运行,必须采用日志机制来报告异常,包括异常发生的时刻,错误说明,可能的原因、严重程度,发生异常或错误的位置等。
异常处理
不允许使用异常实现来控制程序的正常流程,异常实现只用于异常和错误发生时如何使程序回到正常流程。在捕获语句的抛出异常子句中,必须抛出原始异常,用以维护原始错误的堆栈分配。
[强制]Java 类库中定义的一类RuntimeException可以通过预先检查进行规避,而不应该通过catch 来处理,比如：IndexOutOfBoundsException,NullPointerException等等。
.
9 / 31
说明：无法通过预检查的异常除外,如在解析一个外部传来的字符串形式数字时,通过catch NumberFormatException来实现。
正例：if <obj != null> {...}
反例：try { <> } catch <NullPointerException e> {...}
[强制]异常不要用来做流程控制,条件控制,因为异常的处理效率比条件分支低。
[强制]对大段代码进行try-catch,这是不负责任的表现。catch时请分清稳定代码和非稳定代码,稳定代码指的是无论如何不会出错的代码。对于非稳定代码的catch尽可能进行区分异常类型,再做对应的异常处理。
[强制]捕获异常是为了处理它,不要捕获了却什