软件开发编码规范说明

软件开发编码规范说明

2017

软件开发编码规范说明梁峰2017-5-31

一、高级语言 (2)

1.1适用范围 (2)

1.2程序风格 (2)

1.2.1.代码缩进 (2)

1.2.2.变量申明 (2)

1.2.3.代码块长度 (2)

1.2.4.代码换行 (2)

1.2.5.空行及空格 (3)

1.3命名 (3)

1.3.1.变量命名 (3)

1.3.2.常量命名 (4)

1.3.3.函数或方法命名 (4)

1.3.4.文件命名 (4)

1.4注释 (5)

1.4.1.代码注释 (5)

1.4.2.变量注释 (5)

1.4.3.函数注释 (5)

1.4.4.文件注释 (6)

1.5错误和异常处理 (6)

1.5.1.错误处理 (6)

1.5.2.异常处理 (6)

1.6注意事项 (8)

1.6.1.变量的使用 (8)

1.6.2.代码实现 (9)

1.7日志规约 (9)

二、结构化查询语言 (11) 2.1.程序风格 (11)

2.1.1.SQL语句 (11)

2.1.2.存储过程 (13)

2.1.3.存储过程命名 (13)

2.1.4.变量命名 (13)

2.1.5.游标命名 (13)

2.1.6.常量命名 (13)

2.2.建表规约 (13)

2.1.安全规约 (15)

2.3.注释 (16)

2.3.1.代码注释 (16)

2.3.2.存储过程注释 (17)

2.3.3.常量及变量注释 (17)

2.4.错误和和异常处理 (17)

2.5.注意事项 (18)

一、高级语言

1.1适用范围

主要针对JSP，CSS和JAVA高级编程语言，其它高级语言可参照执行。

1.2程序风格

1.2.1.代码缩进

程序块（包括函数、过程、结构的定义及循环、判断等语句）要严格采用缩进风格编写，对齐只使用空格键，不使用TAB键，所有的缩进为4个空格。

1.2.2.变量申明

在函数内部申明变量时，必须在函数的开始位置。

1.2.3.代码块长度

单个函数的程序行数不得超过200行。一个程序文件的长度不得超过5000行代码。

1.2.4.代码换行 1.较长的语句（>80字符）要分成多行书写，长表达式要在低优先级操作

符处划分新行，操作符放在新行之首，划分出的新行要进行适当的缩进，

使排版整齐，语句可读。

2.不允许把多个短语句写在一行中，即一行只允许写一条语句（如if 、

for 、do 、while、case 、switch等语句自占一行）。

3.程序块的分界符必须各自独占一行并且位于同一列，同时与引用它们的

语句左对齐。

1.2.5.空行及空格

1.通过摘要注释分隔的两个代码块之间、局部变量和它后边的语句之间、

函数之间留一个空行。

2.在所有关键字和逗号之后要留一个空格，方法名之后不要留空格，紧跟

左括号“（”，以与关键字区别。

3.如果“;”不是一行的结束符号，其后要留空格，如for

(initialization;

condition; update)。

4.赋值操作符、比较操作符、算术操作符、逻辑操作符、位域操作符，如

“=”、“+=” “>=”、“<=”、“+”、“*”、“%”、“&&”、“||”、

“<<”，“^”等二元操作符的前后要加空格。

5.一元操作符如“!”、“~”、“++”、“--”、“&”（地址运算符）等

前后不加空格。诸如“［］”、“.”、“->”这类操作符前后不加空格。 1.3命名

1.3.1.变量命名

1.变量的名字须使用“名词”或者“形容词＋名词”。变量的命名要求符

合匈牙利命名法则，即开头字母用变量的类型（第一个字母小写），其

余部分用变量的英文意思或其英文意思的缩写（尽量避免用中文的拼音），中间单词的第一个字母要大写。即：变量名=变量类型+变量的英文意思

（或缩写）。

2.变量名称须准确、完整地描述变量的含义。循环计数变量的名称须有含

义。如果循环语句的长度超过了两行或者存在着嵌套循环，避免使用i、

j或k之类的变量，须使用有意义的变量，有利于程序的理解。（单字

符的变量名一般只用于生命期非常短暂的变量）。

3.对于所有布尔型变量的命名，能够直接从名称上看出为真的条件。枚举

类型的变量名称须包含基础类型，以方便分辨变量的类型。例如，用

Color变量表示ColorRed和ColorGreen枚举类型的值。

4.在所有全局变量前首字母必须使用‘v’，接口指针必须使用“pi”，

后跟接口名称缩写。在申明变量时要避免局部变量与公共变量同名、块

内部变量与它外部变量同名。

1.3.

2.常量命名

常量的命名须代表抽象的实体，而非它们所代表的值，即对于涉及物理状态或者含有物理意义的常量，不允许直接使用不易理解的数字，必须用有意义的枚举或宏来代替。所有常量名均全部大写，由英文或其缩写，单词间以‘_’隔开，如int MAX_NUM。

1.3.3.函数或方法命名

函数或方法的命名应该尽量用英文表达出函数或方法完成的功能。遵循动宾结构的命名法则，函数或方法名中动词在前，类的成员函数或方法须只使用“动词”，第一个字母是小写，但是中间单词的第一个字母是大写。如果是返回一个成员变量的值，名称一般为get+成员变量名，如若返回的值是bool变量，一般以is作为前缀。如果是修改一个成员变量的值，名称一般为：set + 成员变量名。函数或方法名的长度不得少于8个字母。

1.3.4.文件命名

文件的名字应该使用名词。每个单词第一个字母须大写。文件的命名应该尽量用英文表达出文件的内容。避免使用单词的缩写，除非它的缩写已经广为人知，如HTTP。文件的名字中应能反映出文件的类型（针对不同的编程语言，有不同类型的文件。要求文件名的长度不得少于5个字母。对于文件中类的命名，前缀用大写字母J，后跟类的功能，中间单词第一个字母要大写。

1.4注释

1.4.1.代码注释

注释将增加代码的清晰度。注释需简洁、明了，含义准确，防止注释二义性，避免在注释中使用缩写，特别是非常用缩写。注释不允许包括其他的特殊字符。可以先写注释，后写代码，但对代码的注释不可放在代码下面，须放在代码上方或右方相邻位置。

1.4.

2.变量注释

1.对于变量的注释必须紧跟在变量的后面说明变量的作用。对于所有有物

理含义的变量、常量、数据结构声明(包括数组、结构、类、枚举等)， 如果其命名不是充分自注释的，在声明时都必须加以注释，说明其物理

含义。原则上对于每个变量都应该注释，但对于意义非常明显的变量，

可以不注释。

2.对于全局变量必须有较详细的注释，包括对其功能、取值范围、哪些函

数或过程存取它以及存取时注意事项等进行说明。

1.4.3.函数注释

1.对于函数，须在函数头部从函数的目的、功能、输入参数、输出参数、

返回值、调用关系（函数、表）、“算法”、“日期”等方面进行注释。

不允许在一行代码或表达式的中间插入注释。在定义函数原型时，须对

每一个参数加以注释。

2.对于函数体内的分支语句（条件分支、循环语句等）必须编写注释，对

于前后顺序不能颠倒的情况，建议在注释中增加序号。对于从一个case

子句进入后续的case子句，须用注释“ Fall through”明确标记。当

代码段较长，特别是多重嵌套时，这样做可以使代码更清晰，更便于阅

读。

3.如果部分代码不再使用，但还要保存，须使用#if UNUSED标识。如果部

分代码目前不能使用，但最后肯定要用，须使用#if LATER标识。使用

“TODO: comment”标记未完成代码，“ BUG: comment”标记错误代码。

1.4.4.文件注释

1.每个源文件有效注释量必须占代码量的20％以上。必须在每个源文件的

头部进行注释，注释须包含：版权说明、版本号、生成日期、作者、主

要函数及其功能的简要说明、与其它文件的关系、修改日志（说明对文

件的修改内容、修改原因以及修改日期）。

2.修改代码的同时必须修改相应的注释，以保证注释与代码的一致性。不

再有用的注释要删除。

1.5错误和异常处理

1.5.1.错误处理

系统在正常状态下以及无重载和硬件失效状态下，不应产生任何异常。发生异常或错误时，对于应用服务层不允许抛出异常中断服务程序的运行，须由系统自行处理保持程序正常运行，必须采用日志机制来报告异常，包括异常发生的时刻，错误说明，可能的原因、严重程度，发生异常或错误的位置等。

1.5.

2.异常处理

不允许使用异常实现来控制程序的正常流程，异常实现只用于异常和错误发生时如何使程序回到正常流程。在捕获语句的抛出异常子句中，必须抛出原始异常，用以维护原始错误的堆栈分配。

1.【强制】Java 类库中定义的一类RuntimeException可以通过预先检查进行

规避，而不应该通过catch 来处理，比如：IndexOutOfBoundsException，NullPointerException等等。

说明：无法通过预检查的异常除外，如在解析一个外部传来的字符串形式数字时，通过catch NumberFormatException来实现。 正例：if (obj != null) {...}

反例：try { obj.method() } catch (NullPointerException e) {...}

2.【强制】异常不要用来做流程控制，条件控制，因为异常的处理效率比条件

分支低。

3.【强制】对大段代码进行try-catch，这是不负责任的表现。catch时请分

清稳定代码和非稳定代码，稳定代码指的是无论如何不会出错的代码。对于非稳定代码的catch尽可能进行区分异常类型，再做对应的异常处理。

4.【强制】捕获异常是为了处理它，不要捕获了却什么都不处理而抛弃之，如

果不想处理它，请将该异常抛给它的调用者。最外层的业务使用者，必须处理异常，将其转化为用户可以理解的内容。

5.【强制】有try块放到了事务代码中，catch异常后，如果需要回滚事务，

一定要注意手动回滚事务。

6.【强制】finally块必须对资源对象、流对象进行关闭，有异常也要做

try-catch。说明：如果JDK7及以上，可以使用try-with-resources方式。

7.【强制】不能在finally块中使用return，finally块中的return返回后

方法结束执行，不会再执行try块中的return语句。

8.【强制】捕获异常与抛异常，必须是完全匹配，或者捕获异常是抛异常的父

类。说明：如果预期对方抛的是绣球，实际接到的是铅球，就会产生意外情况。

9.【推荐】方法的返回值可以为null，不强制返回空集合，或者空对象等，必