软件开发编码规范说明文档格式.docx
《软件开发编码规范说明文档格式.docx》由会员分享，可在线阅读，更多相关《软件开发编码规范说明文档格式.docx（18页珍藏版）》请在冰豆网上搜索。
<
”，“^”等二元操作符的前后要加空格。
5.一元操作符如“!
”、“~”、“++”、“--”、“&
”（地址运算符）等前后不加空格。
诸如“［］”、“.”、“->
”这类操作符前后不加空格。
1.3命名
1.3.1.变量命名
1.变量的名字须使用“名词”或者“形容词＋名词”。
变量的命名要求符合匈牙利命名法则，即开头字母用变量的类型（第一个字母小写），其余部分用变量的英文意思或其英文意思的缩写（尽量避免用中文的拼音），中间单词的第一个字母要大写。
即：
变量名=变量类型+变量的英文意思（或缩写）。
2.变量名称须准确、完整地描述变量的含义。
循环计数变量的名称须有含义。
如果循环语句的长度超过了两行或者存在着嵌套循环，避免使用i、j或k之类的变量，须使用有意义的变量，有利于程序的理解。
（单字符的变量名一般只用于生命期非常短暂的变量）。
3.对于所有布尔型变量的命名，能够直接从名称上看出为真的条件。
枚举类型的变量名称须包含基础类型，以方便分辨变量的类型。
例如，用Color变量表示ColorRed和ColorGreen枚举类型的值。
4.在所有全局变量前首字母必须使用‘v’，接口指针必须使用“pi”，后跟接口名称缩写。
在申明变量时要避免局部变量与公共变量同名、块内部变量与它外部变量同名。
1.3.2.常量命名
常量的命名须代表抽象的实体，而非它们所代表的值，即对于涉及物理状态或者含有物理意义的常量，不允许直接使用不易理解的数字，必须用有意义的枚举或宏来代替。
所有常量名均全部大写，由英文或其缩写，单词间以‘_’隔开，如intMAX_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子句，须用注释“Fallthrough”明确标记。
当代码段较长，特别是多重嵌套时，这样做可以使代码更清晰，更便于阅读。
3.如果部分代码不再使用，但还要保存，须使用#ifUNUSED标识。
如果部分代码目前不能使用，但最后肯定要用，须使用#ifLATER标识。
使用“TODO:
comment”标记未完成代码，“BUG:
comment”标记错误代码。
1.4.4.文件注释
1.每个源文件有效注释量必须占代码量的20％以上。
必须在每个源文件的头部进行注释，注释须包含：
版权说明、版本号、生成日期、作者、主要函数及其功能的简要说明、与其它文件的关系、修改日志（说明对文件的修改内容、修改原因以及修改日期）。
2.修改代码的同时必须修改相应的注释，以保证注释与代码的一致性。
不再有用的注释要删除。
1.5错误和异常处理
1.5.1.错误处理
系统在正常状态下以及无重载和硬件失效状态下，不应产生任何异常。
发生异常或错误时，对于应用服务层不允许抛出异常中断服务程序的运行，须由系统自行处理保持程序正常运行，必须采用日志机制来报告异常，包括异常发生的时刻，错误说明，可能的原因、严重程度，发生异常或错误的位置等。
1.5.2.异常处理
不允许使用异常实现来控制程序的正常流程，异常实现只用于异常和错误发生时如何使程序回到正常流程。
在捕获语句的抛出异常子句中，必须抛出原始异常，用以维护原始错误的堆栈分配。
1.【强制】Java类库中定义的一类RuntimeException可以通过预先检查进行规避，而不应该通过catch来处理，比如：
IndexOutOfBoundsException，NullPointerException等等。
说明：
无法通过预检查的异常除外，如在解析一个外部传来的字符串形式数字时，通过catchNumberFormatException来实现。
正例：
if（obj!
=null）{...}
反例：
try{obj.method（）}catch（NullPointerExceptione）{...}
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，不强制返回空集合，或者空对象等，必须添加注释充分说明什么情况下会返回null值。
调用方需要进行null判断防止NPE问题。
本手册明确防止NPE是调用者的责任。
即使被调用方法返回空集合或者空对象，对调用者来说，也并非高枕无忧，必须考虑到远程调用失败、序列化失败、运行时异常等场景返回null的情况。
10.【推荐】防止NPE，是程序员的基本修养，注意NPE产生的场景：
♦返回类型为基本数据类型，return包装数据类型的对象时，自动拆箱有可能产生NPE。
publicintf（）{returnInteger对象}，如果为null，自动解箱抛NPE。
♦数据库的查询结果可能为null。
♦集合里的元素即使isNotEmpty，取出的数据元素也可能为null。
♦远程调用返回对象时，一律要求进行空指针判断，防止NPE。
♦对于Session中获取的数据，建议NPE检查，避免空指针。
♦级联调用obj.getA（）.getB（）.getC（）；
一连串调用，易产生NPE。
使用JDK8的Optional类来防止NPE问题。
11.【推荐】定义时区分unchecked/checked异常，避免直接抛出newRuntimeException（），更不允许抛出Exception或者Throwable，应使用有业务含义的自定义异常。
推荐业界已定义过的自定义异常，
♦如：
DAOException/ServiceException等。
12.【参考】在代码中使用“抛异常”还是“返回错误码”，对于公司外的http/api开放接口必须使用“错误码”；
而应用内部推荐异常抛出；
跨应用间RPC调用优先考虑使用Result方式，封装isSuccess（）方法、“错误码”、“错误简短信息”。
关于RPC方法返回方式使用Result方式的理由：
♦使用抛异常返回方式，调用方如果没有捕获到就会产生运行时错误。
♦如果不加栈信息，只是new自定义异常，加入自己的理解的errormessage，对于调用端解决问题的帮助不会太多。
如果加了栈信息，在频繁调用出错的情况下，数据序列化和传输的性能损耗也是问题。
13.【参考】避免出现重复的代码（Don’tRepeatYourself），即DRY原则。
随意复制和粘贴代码，必然会导致代码的重复，在以后需要修改时，需要修改所有的副本，容易遗漏。
必要时抽取共性方法，或者抽象公共类，甚至是共用模块。
一个类中有多个public方法，都需要进行数行相同的参数校验操作，这个时候请抽取：
privatebooleancheckParam（DTOdto）{...}
1.6注意事项
1.6.1.变量的使用
1.公共变量是增大模块间耦合的重要原因之一，在开发过程中能不用公共变量尽量不要使用。
2.临时或局部变量，使用时必须首先初始化，严禁使用未经初始化的变量作为右值。
初始化类的实例时，除非十分必要，否则不要赋null值，在创建新对象时必须检查返回值，或者采用标准方法处理内存管理错误。
3.尽量不要提供public和protected的成员变量，应使用属性来代替。
1.6.2.代码实现
1.不要在程序中使用运算符的默认优先级，应使用括号明确表达式的操作顺序。
2.对于要返回指针但可能出错的函数，应返回一个BOOL值和指向参数的指针。
3.每个接口不应该只有一个成员，最多也不应超过20个，尽量使每个接口中包含3－5个成员，并且接口成员中不要包含事件。
4.如果只有成员函数或操作符，应该使用类，而不用结构。
5.定义类成员时，应明确定义其属性public、protected或private，并按照此顺序分组定义。
在类中不要说明全局数据成员，可以使用内嵌访问函数，以提高性能。
6.不要使用虚函数，如多态，除非必须使用，因为虚函数的开销较大，如果使用多态，其基类的构造函数必须是虚函数。
为了清楚其间，重载虚方法时，应明确说明为virtual。
7.在实现构造函数时，最好不要实现复杂费时的功能，但要确保初始化所有数据成员。
同时要保证构造函数、析构函数不能失败，应在一个方法中实现内存分配，或潜在的错误处理。
如果部分资源在析构函数执行之前释放，要确保全部域复位，如释放对象并将指针置为NULL，以避免多次释放出现异常。
8.每个类最好存放在单独的文件中，并且一个文件只能有一个命名空间，避免将多个命名空间放在同一个文件里面，每个命名空间对应一个目录。
1.7日志规约
1.【强制】应用中不可直接使用日志系统（Log4j、Logback）中的API，而应依赖使用日志框架SLF4J中的API，使用门面模式的日志框架，有利于维护和各个类的日志处理方式统一。
importorg.slf4j.Logger;
importorg.slf4j.LoggerFactory;
privatestaticfinalLoggerlogger=LoggerFactory.getLogger（Abc.class）;
2.【强制】日志文件推荐至少保存15天，因为有些异常具备以“周”为频次发生的特点。
3.【强制】应用中的扩展日志（如打点、临时监控、访问日志等）命名方式：
appName_logType_logName.log。
logType:
日志类型，推荐分类有stats/desc/monitor/visit等；
logName:
日志描述。
这种命名的好处：
通过文件名就可知道日志文件属于什么应用，什么类型，什么目的，也有利于归类查找。
mppserver应用中单独监控时区转换异常。
如：
mppserver_monitor_timeZoneConvert.log
推荐对日志进行分类，如将错误日志和业务日志分开存放，便于开发人员查看，也便于通过日志对系统进行及时监控。
4.【强制】对trace/debug/info级别的日志输出，必须使用条件输出形式或者使用占位符的方式。
logger.debug（"
Processingtradewithid:
"
+id+"
symbol:
+symbol）;
如果日志级别是warn，上述日志不会打印，但是会执行字符串拼接操作，如果symbol是对象，会执行toString（）方法，浪费了系统资源，执行了上述操作，最终日志却没有打印。
（条件）
if（logger.isDebugEnabled（））{
}
（占位符）
{}symbol:
{}"
id,symbol）;
5.【强制】避免重复打印日志，浪费磁盘空间，务必在log4j.xml中设置additivity=false。
loggername="
com.taobao.dubbo.config"
additivity="
false"
>
6.【强制】异常信息应该包括两类信息：
案发现场信息和异常堆栈信息。
如果不处理，那么通过关键字throws往上抛出。
logger.error（各类参数或者对象toString+"
_"
+e.getMessage（）,e）;
7.【推荐】谨慎地记录日志。
生产环境禁止输出debug日志；
有选择地输出info日志；
如果使用warn来记录刚上线时的业务行为信息，一定要注意日志输出量的问题，避免把服务器磁盘撑爆，并记得及时删除这些观察日志。
大量地输出无效日志，不利于系统性能提升，也不利于快速定位错误点。
记录日志时请思考：
这些日志真的有人看吗？
看到这条日志你能做什么？
能不能给问题排查带来好处？
8.【参考】可以使用warn日志级别来记录用户输入参数错误的情况，避免用户投诉时，无所适从。
注意日志输出的级别，error级别只记录系统逻辑出错、异常等重要的错误信息。
如非必要，请不要在此场景打出error级别。
二、结构化查询语言
2.1.程序风格
2.1.1.SQL语句
1.【强制】不要使用count（列名）或count（常量）来替代count（*），count（*）是SQL92定义的标准统计行数的语法，跟数据库无关，跟NULL和非NULL无关。
count（*）会统计值为NULL的行，而count（列名）不会统计此列为NULL值的行。
2.【强制】count（distinctcol）计算该列除NULL之外的不重复行数，注意count（distinctcol1,col2）如果其中一列全为NULL，那么即使另一列有不同的值，也返回为0。
3.【强制】当某一列的值全是NULL时，count（col）的返回结果为0，但sum（col）的返回结果为NULL，因此使用sum（）时需注意NPE问题。
可以使用如下方式来避免sum的NPE问题：
SELECTIF（ISNULL（SUM（g））,0,SUM（g））FROMtable;
4.【强制】使用ISNULL（）来判断是否为NULL值。
注意：
NULL与任何值的直接比较都为NULL。
♦NULL<
NULL的返回结果是NULL，而不是false。
♦NULL=NULL的返回结果是NULL，而不是true。
1的返回结果是NULL，而不是true。
5.【强制】在代码中写分页查询逻辑时，若count为0应直接返回，避免执行后面的分页语句。
6.【强制】不得使用外键与级联，一切外键概念必须在应用层解决。
（概念解释）学生表中的student_id是主键，那么成绩表中的student_id则为外键。
如果更新学生表中的student_id，同时触发成绩表中的student_id更新，则为级联更新。
外键与级联更新适用于单机低并发，不适合分布式、高并发集群；
级联更新是强阻塞，
存在数据库更新风暴的风险；
外键影响数据库的插入速度。
7.【强制】禁止使用存储过程，存储过程难以调试和扩展，更没有移植性。
8.【强制】数据订正时，删除和修改记录时，要先select，避免出现误删除，确认无误才能执行更新语句。
9.【推荐】in操作能避免则避免，若实在避免不了，需要仔细评估in后边的集合元素数量，控制在1000个之内。
10.【参考】如果有全球化需要，所有的字符存储与表示，均以utf-8编码，注意字符统计函数的区别。
SELECTLENGTH（"
轻松工作"
）；
返回为12
SELECTCHARACTER_LENGTH（"
返回为4
如果要使用表情，那么使用utfmb4来进行存储，注意它与utf-8编码的区别。
11.【参考】TRUNCATETABLE比DELETE速度快，且使用的系统和事务日志资源少，但TRUNCATE无事务且不触发trigger，有可能造成事故，故不建议在开发代码中使用此语句。
TRUNCATETABLE在功能上与不带WHERE子句的DELETE语句相同。
2.1.2.存储过程
a）在存储过程内部申明变量时，必须在存储过程的开始位置；
b）通过摘要注释分隔的两个语句块之间、局部变量和它后边的语句之间留一个空行。
2.1.3.存储过程命名
用户存储过程要按照：
USP_+系统模块缩写+功能标识+表名（不带前缀）或功能的英文单词或英文单词缩写的方式命名。
2.1.4.变量命名
存储过程中变量名全部采用小写，局部变量名使用“v_”开头，输入参数以“i_开头，输出参数以“o_”开头，输入输出参数用io_开头。
所有输入参数必须显示声明。
当变量代表列时，应使用%TYPE属性对变量命名。
2.1.5.游标命名
游标应统一用后缀“_cur”命名。
2.1.6.常量命名
常量应统一用cn_的前缀命名。
2.2.建表规约
1.【强制】表达是与否概念的字段，必须使用is_xxx的方式命名，数据类型是unsignedtinyint（1表示是，0表示否）。
任何字段如果为非负数，必须是unsigned。
表达逻辑删除的字段名is_deleted，1表示删除，0表示未删除。
2.【强制】表名、字段名必须使用小写字母或数字，禁止出现数字开头，禁止两个下划线中间只出现数字。
数据库字段名的修改代价很大，因为无法进行预发布，所以字段名称需要慎重考虑。
getter_admin，task_config，level3_name
GetterAdmin，taskConfig，level_3_name
3.【强制】表名不使用复数名词。
表名应该仅仅表示表里面的实体内容，不应该表示实体数量，对应于DO类名也是单数形式，符合表达习惯。
4.【强制】禁用保留字，如desc、range、match、delayed等，请参考MySQL官方保留字。
5.【强制】主键索引名为pk_字段名；
唯一索引名为uk_字段名；
普通索引名则为idx_字段名。
pk_即primarykey；
uk_即uniquekey；
idx_即index的简称。
6.【强制】小数类型为decimal，禁止使用float和double。
float和double在存储的时候，存在精度损失的问题，很可能在值的比较时，得到不正确的结果。
如果存储的数据范围超过decimal的范围，建议将数据拆成整数和小数分开存储。
7.【强制】如果存储的字符串长度几乎相等，使用char定长字符串类型。
8.【强制】varchar是可变长字符串，不预先分配存储空间，长度不要超过5000，如果存储长度大于此值，定义字段类型为text，独立出来一张表，用主键来对应，避免影响其它字段索引效率。
9.【强制】表必备三字段：
id,gmt_create,gmt_modified。
其中id必为主键，类型为unsignedbigint、单表时自增、步长为1。
gmt_create,gmt_modified的类型均为date_time类型。
10.【推荐】表的命名最好是加上“业务名称_表的作用”。
tiger_task/ti
升级会员 