代码编写规范精选文档.docx
- 文档编号:4562945
- 上传时间:2022-12-06
- 格式:DOCX
- 页数:10
- 大小:22.97KB
代码编写规范精选文档.docx
《代码编写规范精选文档.docx》由会员分享,可在线阅读,更多相关《代码编写规范精选文档.docx(10页珍藏版)》请在冰豆网上搜索。
代码编写规范精选文档
TTMSsystemofficeroom【TTMS16H-TTMS2A-TTMS8Q8-TTMSHHJ8】
代码编写规范精选文档
知识管理系统代码编写规范
一、介绍
本文档为《知识管理系统》代码编写规范,为保证代码风格的一致性和后期的可维护性,文档讲述的内容要求所有开发人员必须遵守。
本规范主要参考了GoogleJavaStyle,包括了其他一些业界约定俗成的公约和普遍采用的标准。
本规范并非最终标准,一些规定还需再做商讨。
术语说明
本文档除非特殊说明,否则:
1.类(class)统指普通类、枚举类、接口和注解类型。
2.注释(comment)只用来指实现注释(implementationcomments)。
我们不使用“文档注释”这样的说法,而会直接说Javadoc。
其他“术语说明”,将在文档中需要说明的地方单独说明。
文档说明
本文档中的代码并不一定符合所有规范。
即使这些代码遵循本规范,但这不是唯一的代码方式。
例子中可选的格式风格也不应该作为强制执行的规范。
二、源码文件基础
文件名
源文件以其最顶层的类名来命名,大小写敏感,文件扩展名为.java。
文件编码:
UTF-8
源码文件使用UTF-8编码。
特殊字符
空格字符
除了换行符外,ASCII水平空白字符(0x20)是源码文件中唯一支持的空格字符。
这意味着:
1.其他空白字符将被转义。
2.Tab字符不被用作缩进控制。
特殊转义字符串
任何需要转义字符串表示的字符(例如\b,\t,\n,\f,\r,\",\'和\\等),采用这种转义字符串的方式表示,而不采用对应字符的八进制数(例如\012)或Unicode码(例如\u000a)表示。
非ASCII字符
对于其余非ASCII字符,直接使用Unicode字符(例如∞),或者对应的Unicode码(例如\u221e)转义都是允许的。
唯一需要考虑的是,何种方式更能使代码容易阅读和理解。
注意:
在使用Unicode码转义,或者甚至是有时直接使用Unicode字符的时候,添加一点说明注释将对别人读懂代码很有帮助。
三、源码文件结构
源码文件按照先后顺序,由以下几部分组成:
1.license或者copyright声明信息。
(如果需要声明)
2.包(package)声明语句。
3.import语句。
4.类声明(每个源码文件只能有一个顶级类)。
每个部分之间应该只有一行空行作为间隔。
license或者copyright的声明信息。
如果需要声明license或copyright信息,应该在文件开始时声明。
包声明
包声明的行没有行长度的限制。
单行长度限制不适用于包声明。
import语句
不使用通配符import
即,不要出现类似这样的import语句:
import.*;
没有行长度限制
import语句的行没有行长度的限制。
单行长度限制不适用于import语句所在行。
顺序和空行
import语句应该被分为几个组,每个组之间由单行的空行隔开。
分组的顺序如下:
1.所有的静态导入为归为一组。
2.(项目自带包)包的import归为一组。
3.第三方包。
每个顶级包归为一组。
第三方包之间按ASCII码排序。
例如:
android,com,junit,org,sun
4.java包归为一组。
5.javax包归为一组。
同一组内的import语句之间不应用空行隔开。
同一组中的import语句按ASCII码排序。
类声明
只声明一个顶级类
每个源码文件中只能有一个顶级类。
例外:
,该文件中可没有package-info类。
类成员顺序
类成员的顺序对代码的易读性有很大影响,但这也不存在唯一的通用法则。
不同的类可能有不同的排序方式。
重要的是,每个类都要按照一定的逻辑规律排序。
维护者应该要能解释这种排序逻辑。
比如,新的方法不能总是习惯性地添加到类的结尾,因为这样就是按时间顺序而非某种逻辑来排序的。
重载方法:
不应该分开
当一个类有多个构造函数,或者多个同名成员方法时,这些函数应该写在一起,不应该被其他成员分开。
四、格式
术语说明:
块状结构(block-likeconstruct)指类、成员函数和构造函数的实现部分(大括号中间部分)。
注意,在后面的节中讲到数组初始化,所有的数组初始化都可以被认为是一个块状结构(非强制)。
大括号
大括号不可省略
大括号一般用在if,else,for,do和while等语句。
即使当它的实现为空或者只有一句话时,也需要使用。
非空语句块采用K&R风格
对于非空语句块,大括号遵循Kernighan&Ritchie风格:
左大括号前不换行。
左大括号后换行。
右大括号前换行。
如果右大括号结束一个语句块或者函数体、构造函数体或者有命名的类体,则右大括号后换行,否则不要换行。
例如,当右大括号后面接else或者逗号时,不应该换行。
例子:
1.returnnewMyClass(){
2.@Overridepublicvoidmethod(){
3.if(condition()){
4.try{
5.someting();
6.}catch(ProblemExceptione){
7.recover();
8.}
9.}
10.}
11.};
一些例外的情况,将在节讲枚举类型的时候讲到。
空语句块:
可以用简洁版本
一个空的语句块,大括号可以简洁地写成{},不需要换行。
如果它是一个多块语句的一部分(if/else或try/catch/finally),即使大括号内没内容,右大括号也要换行。
例子:
1.voiddoNothing(){}
语句块的缩进:
4空格
每当一个新的语句块产生,缩进就增加两个空格。
当这个语句块结束时,缩进恢复到上一层级的缩进格数。
缩进要求对整个语句块中的代码和注释都适用。
(例子可参考之前节中的例子)。
一行最多只有一句代码
每句代码的结束都需要换行。
行长度限制:
80或100
不同的项目可以选择采用80个字符或者100个字符作为限制。
除了以下几个特殊情况外,其他代码内容都需要遵守这个长度限制。
这在节会有详细解释。
例外:
1.按照行长度限制,无法实现地方(例如:
Javadoc中超长的URL地址,或者一个超长的JSNI方法的引用);
2.package和import语句不受长度限制。
(见、节);
3.注释中的命令行指令行,将被直接复制到shell中执行的。
换行
术语说明:
当一行代码按照其他规范都合法,只是为了避免超出行长度限制而换行时,称为长行断行。
长行断行,没有一个适合所有场景的全面、确定的规范。
但很多相同的情况,我们经常使用一些行之有效的断行方法。
注意:
将长行封装为函数,或者使用局部变量的方法,也可以解决一些超出行长度限制的情况。
并非一定要断行。
在何处断行
断行的主要原则是:
选择在更高一级的语法逻辑的地方断行。
其他一些原则如下:
1.在一个逗号后面断开。
2.在一个操作符前面断开(=号和foreach语句的冒号除外)。
3.在调用函数或者构造函数需要断行时,与函数名相连的左括号要在一行。
也就是在左括号之后断行。
断行的缩进:
至少8个字符
当断行之后,在第一行之后的行,我们叫做延续行。
每一个延续行在第一行的基础上至少缩进四个字符。
当原行之后有多个延续行的情况,缩进可以大于8个字符。
如果多个延续行之间由同样的语法元素断行,它们可以采用相同的缩进。
节介绍水平对齐中,解决了使用多个空格与之前行缩进对齐的问题。
空白
垂直空白
以下情况需使用一个空行:
1.类成员之间需要空行隔开:
字段、构造函数、方法、内部类、静态初始化语句块(staticinitializers)、实例初始化语句块(instanceinitializers)。
2.
o例外:
连续字段之间的空白行不是必需的。
一般多个字段中间的空行,是为了对字段做逻辑上的分组。
3.在函数体内,语句的逻辑分组间使用空行。
4.类的第一个成员之前,或者最后一个成员结束之后,用空行间隔。
(可选)
5.本文档中其他部分介绍的需要空行的情况。
(例如节中的import语句)
单空行时使用多行空行是允许的,但是不要求也不鼓励。
水平空白
除了语法和规范的其他规则,词语分隔、注释和Javadoc外,水平的ASCII空格只在以下情况出现:
1.所有保留的关键字与紧接它之后的位于同一行的左括号(()之间需要用空格隔开。
(例如if、for、catch)
2.所有保留的关键字与在它之前的右大括号(})之间需要空格隔开。
(例如else、catch)
3.在左大括号({)之前都需要空格隔开。
只有两种例外:
4.
o@SomeAnnotation({a,b})
oString[][]x={{"foo"}};
5.所有的二元运算符和三元运算符的两边,都需要空格隔开。
一元操作符和操作数之间不应该加空格,比如:
负号(“-”),自增(“++”)和自减(“--”)。
例:
i++;
6.逗号、冒号、分号和右括号之后。
1.如果在一条语句后做注释,则双斜杠.}
例外:
如果注解只有一个,并且不带参数。
则它可以和类或方法名放在同一行。
例如:
1.@OverridepublicinthashCode(){...}
注解应用到字段时,也是紧接Javadoc之后。
不同的是,多个注解可以放在同一行。
例如:
1.@Partial@MockDataLoaderloader;
对于参数或者局部变量使用注解的情况,没有特定的规范。
注释
语句块的注释风格
注释的缩进与它所注释的代码缩进相同。
可以采用/*...*/进行注释,也可以用.进行注释。
当使用/*...*/进行多行注释时,每一行都应该以*开始,并且*应该上下对齐。
注意文字和注释符之间有一个空格(水平空白)。
例如:
1./*
2.*Thisis*evendothis.*/
3.*/
提示:
多行注释时,如果你希望集成开发环境能自动对齐注释,你应该使用/*...*/,.一般不会自动对齐。
修饰符
多个类和字段的修饰符,按《JavaLanguageSpecification》中介绍的先后顺序排序。
具体是:
1.publicprotectedprivateabstractstaticfinaltransientvolatilesynchronizednativestrictfp
数字型的字面值
long类型的字面值使用大写L为后缀,永远不要使用小写l(避免和1混淆)。
例如:
00L
五、命名
适用于所有命名标识符的通用规范
标示符只应该使用ASCII字母、数字,字母大小写敏感。
因此所有的标示符,都应该能匹配正则表达式\w+。
标示符不需要使用特殊的前缀或后缀,如name_,mName,s_name和kName,在Java编程风格中都不再使用。
不同类型的标示符规范
包名
包名全部用小写字母,将各单词简单地连在一起(不使用下划线)。
例如:
,不要使用或。
类名
类名都以UpperCamelCase风格编写。
类名一般使用名词或名词短语,例如:
Character或ImmutableList。
接口名称一般也使用名词或名词短语(如:
List),有时也可以使用形容词或形容词短语(如:
Readable)。
还没有特定的规则或行之有效的约定来命名注解类型。
测试类的命名,应该以它所测试的类的名字为开头,并在最后加上Test结尾。
例如:
HashTest、HashIntegrationTest。
方法名
方法名都以lowerCamelCase风格编写。
方法命名一般使用动词或者动词短语,例如:
sendMessage或stop。
在JUnit的测试方法中,可以使用下划线,用来区分逻辑组件的名字,经常使用如下的结构:
test
例如:
testPop_emptyStack。
并不存在唯一正确的方式来命名测试方法。
常量名
常量命名,全部使用大写字符,词与词之间用下划线隔开。
(CONSTANCE_CASE)。
常量的定义:
每个常量都是一个静态final字段,但不是所有静态final字段都是常量。
在决定一个字段是否是一个常量时,考虑它是否真的感觉像是一个常量。
例如,如果任何一个该实例的观测状态是可变的,则它几乎肯定不会是一个常量。
只是永远不打算改变对象一般是不够的,它要真的一直不变才能将它示为常量。
下面是常量和非常量的例子:
1..;
1.();StaticMethod();.
2.*/
3.publicintmethod(Stringp1){...}
或者为单行格式:
1./**AnespeciallyshortbitofJavadoc.*/
通用格式在任何时候使用都是可以的。
当Javadoc块只有一行时,可以使用单行格式来替代通用格式。
段落
空白行:
是指Javadoc中,上下两个段落之间只有上下对齐的*字符的行。
每个段落的第一行在第一个字符之前,有一个
标签,并且之后不要有任何空格。
Javadoc标记
所有标准的Javadoc标记,应该按照如下的顺序添加:
@param、@return、@throws、@deprecated。
并且如果这四种Javadoc标记出现,描述都不能为空。
当@从句无法在一行写完时,应该断行。
延续行在第一行的@字符的位置,缩进至少4个字符单位。
摘要片段
每个类或者成员的Javadoc,都是由一个摘要片段开始的。
这个片段非常重要。
因为它是类或者方法在使用时唯一能看到的文本说明。
主要摘要只是一个片段,应该是一个名词短语或者动词短语,而不应该是一个完整的句子。
不应该以类似于:
A{@codeFoo}isa...或Thismethodreturns...这样的开头,但是它应该像一个完整的句子一样使用标点符号。
提示:
一种常见的错误是把单行形式的Javadoc写成:
/**@returnthecustomerID*/,这是不对的。
应该改为:
/**ReturnsthecustomerID.*/。
何处应该使用Javadoc
至少Javadoc应该应用于所有的public类、public和protect的字段和方法。
以下是一些例外:
例外:
方法本身已经足够说明的情况
当方法本身很显而易见时,不需要Javadoc。
例如:
getFoo。
没有必要加上Javadoc说明“Returnsthefoo”。
单元测试中的方法基本都能通过方法名,显而易见地知道方法的作用。
因此不需要增加Javadoc。
重要:
如果有一些相关信息是需要读者了解的,那么以上的例外不应作为忽视这些信息的理由。
例如,对于方法名getCannicalName,就不应该忽视文档说明,因为读者很可能不知道词语canonicalname指的是什么。
例外:
重载方法
重载方法有时不需要再写Javadoc。
例外:
可选的Javadoc
对于包外不可见的类和方法,如有需要,也是要使用Javadoc的。
如果一个注释是用来定义一个类,方法,字段的整体目的或行为,那么这个注释应该写成Javadoc,这样更统一更友好。
注:
本规范的大部分内容可用Eclipse格式化工具自动完成,所以提交代码时使用一次代码格式化是不错的选择。
代码整洁
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 代码 编写 规范 精选 文档