对于软件开发而言,我们必须保证软件的质量,而好的编码规范则是提高我们代码质量的有效的工具之一。
一、 编码规范的作用:
1)提高代码可读性。编码规范,拥有一个良好的编码风格,使得代码具有一定的描述性。有经验的程序员可以短时间内理解代码,弄清代码的状况。新人也可以很快适应编码环境,理解代码含义,同时也帮助程序员们养成良好的编码习惯。
2) 促进团队合作。开发软件,不可能是一个程序员的工作,这需要团队的合作。拥有统一的代码规范,可以使得团队在合作时候减少一些不必要的麻烦,使得代码整合能顺利完成。
3) 减少bug处理。如果没有规范处理输入输出参数,没有规范的异常处理,没有规范的日志处理等等,不仅会引起出现类似空指针这样低级的bug而且还很难找到引起bug的原因。在规范的开发中,查找、处理bug相对来说会变得容易一些。
4)降低维护成本。一个软件的生命周期中,80%的花费在于维护,规范的代码可以减少维护人员的理解时间,易于二次开发,统一的风格还有利于长期的维护。
5)养成代码规范的习惯,有益于程序员自身的成长。随着程序员自己写的代码越来越多,如果没有规范的代码,到后期对代码进行代码审查、测试维护,有可能程序员自身都会陷入代码混乱之中,更别提其他人看代码,肯定也会是一头雾水。规范的代码更有利于帮助程序员理解开发语言、理解模式、理解架构、快速提升开发水平。同时也帮助编程人员写出易理解。易维护、易扩展的优秀代码
二、编码规范的规则
1)排版规则
a 程序块采用缩进4个空格位
b "{"、" }" 最好独占一行,位于同一列。即使是能省略的地方,最好不要省略。
c 较长的语句、表达式、参数最好书写多行
d 一行最好只写一条语句
e 选择语句、循环语句、分支语句的关键词如if ……else/switch/do……while等等,最好独占一行。
f 相对独立的业务语句块之间,变量说明后加上空行
g 对齐使用空格,不采用TAB,避免不同编辑器对TAB处理不同
h 类属性和方法不用交叉放置,不同存取范围的属性或方法也不远交叉放置
……
以上是排版的规范,当然肯定不止这些。
2) 注释规范
a 函数内部(模块内部)注释:
每行代码都应该存在注释,注释应该放置语句的上方或右侧;注释必须与备注是的语句同缩进;注释与上面的代码用一个空行隔开,对if/switch/case/while/do while 必须注释;修改代码也要加上注释;注释内容必须明确,使用易理解的词语。
b 函数外部(或者是模块间)注释:
对每个模块进行注释,如包、文件、类、接口、类属性、方法注释等等,选择不同的语言会有不同的注释方法,应该尤其注意。最好注释到这些模块的开头部分,注释中要包括:其输入参数、输出值、功能、【抛出的异常】、作者,如有修改最好加上修改时间、修改人、修改日志、版本号等等
3)命名规范
a 包的命名:常用命名方式:com.项目名.模块名,所有名称全部小写.
b 类名和接口名的命名:尽量使用完整的英文描述,首字母大写,每个英文单词的首字母大写,其余字母小写。抽象类请以Abstract开头,接口的实现类请以Impl接口,工具类请以Util或Utils结尾,如下列命名方式:StaffService、DefaultStaffService、AbstractEntity、StringUtils;
c 方法命名:尽量使用完整的英文描述,首字母小写,每个英文单词的首字母大写,其余字母小写,属性存取尽量使用setX、getX,返回布尔类型值的方法尽量使用isX,如下列命名方式: queryStaffById、isCodeExists()、getValue
d 属性命名:尽量使用完整的英文描述,首字母小写,每个英文单词的首字母大写,其余字母小写,属性名和方法名不要重复;
e 常量命名:所有单词首字母大写并用“_”分隔。变量之前近可能使用final修饰,注意:枚举也是一种常量,使用名词的复数形式来命名标记枚举,不要给枚举类型值的名字加前缀,不要添加“Enum”或“Flag”后缀。
f 准确控制类成员方法的修饰符,如果仅限于类内部使用用private修饰,可供子类或本包内部使用用protected修饰,对所有公开,则用public;
g 组件命名:尽量以组件类型结果,如:StaffService、OrgService;
h 数据库命名:
表:“模块名_表名”,
字段:bool类型用“Is”、“Can”、“Has”等表示;日期类型命名必须包含“Date”;时间类型必须包含“Time”。
存储过程:使用“proc_”前缀。
视图:使用“view_”前缀。
触发器:使用“trig_”前缀。
i 属性和方法的命名不易过长,一般不超过15个字母;
三 如何写规范的代码
注意:
1)包结构清晰,类、接口、方法、属性命名贴切易懂;
2)该注释的地方注释,注释清楚、易懂,没有二义性;
3)接口定义明确,精确方法功能,每个方法只实现一个功能;
4)方法内部的代码行数控制在200行以内,一个类的代码行数控制在1000行以内,如果你的类代码在1000行以上,请重新思考设计思路,这里说的代码行数不把注释计算在内;
5)多个方法内部如果有相似的功能代码块,应该提取为公用方法;
6)尽量将业务相近的方法放在一起,便于寻找,如:要连接到数据库的模型最好放到一起;
7)对于方法抛出的自定义异常,应该写明异常描述信息;
8)明确数据类型,避免数据类型转换
9)未完成的功能使用TODO标记。