代码编写规范_第1页
代码编写规范_第2页
代码编写规范_第3页
代码编写规范_第4页
代码编写规范_第5页
已阅读5页,还剩8页未读 继续免费阅读

下载本文档

版权说明:本文档由用户提供并上传,收益归属内容提供方,若内容存在侵权,请进行举报或认领

文档简介

1、知识管理系统代码编写规范一、介绍本文档为知识管理系统代码编写规范,为保证代码风格的一致性和后期的可 维护性,文档讲述的内容要求所有开发人员必须遵守。本规范主要参考了 Google Java Style ,包括了其他一些业界约定俗成的公约和 普遍采用的标准。本规范并非最终标准,一些规定还需再做商讨。术语说明本文档除非特殊说明,否则:1. 类(class )统指普通类、枚举类、接口和注解类型。2. 注释(comment)只用来指实现注释(implementation comments)。我们不使用“文 档注释”这样的说法,而会直接说Javadoc。其他“术语说明”,将在文档中需要说明的地方单独说明

2、。文档说明本文档中的代码并不一定符合所有规范。即使这些代码遵循本规范,但这不是唯一的代码方式。例子中可选的格式风格也不应该作为强制执行的规范。二、源码文件基础文件名源文件以其最顶层的类名来命名,大小写敏感,文件扩展名为.java o文件编码:UTF-8源码文件使用UTF-8编码。特殊字符空格字符除了换行符外,ASCII水平空白字符(0x20)是源码文件中唯一支持的空格字符。 这意味着:1. 其他空白字符将被转义。2. Tab字符不被用作缩进控制。特殊转义字符串任何需要转义字符串表示的字符 (例如b ,?t ,?n ,?f ,?r ,?" ,?'和 等),采 用这种转义字符串的

3、方式表示,而不采用对应字符的八进制数(例如 2012)或 Unicode 码(例如?u000a )表示。非ASCII字符对于其余非ASCII字符,直接使用Unicode字符(伤J如?°°),或者对应的Unicode码(例如?u221e)转义都是允许的。唯一需要考虑的是,何种方式更能使代码 容易阅读和理解。注意:在使用Unicode码转义,或者甚至是有时直接使用 Unicode字符的时候, 添加一点说明注释将对别人读懂代码很有帮助。三、源码文件结构源码文件按照先后顺序,由以下几部分组成:1. license 或者copyright 声明信息。(如果需要声明)2. 包(pack

4、age)声明语句。3. import 语句。4. 类声明(每个源码文件只能有一个顶级类)。每个部分之间应该只有一行空行作为间隔。license 或者 copyright 的声明信息。如果需要声明license 或copyright 信息,应该在文件开始时声明。包声明包声明的行没有行长度的限制。单行长度限制不适用于包声明。import 语句不使用通配符import即,不要出现类似这样的import语句:import.*;没有行长度限制import语句的行没有行长度的限制。单行长度限制不适用于import语句所在 行。顺序和空行import语句应该被分为几个组,每个组之间由单行的空行隔开。分组的顺

5、序如 下:1. 所有的静态导入为归为一组。2. (项目自带包)包白im import归为一组。3. 第三方包。每个顶级包归为一组。第三方包之间按ASCII码排序。例如:android,?com,?junit,org,?sun4. java?包归为一组。5. javax?包归为一组。同一组内的import语句之间不应用空行隔开。同一组中的import语句按ASCII 码排序。类声明只声明一个顶级类每个源码文件中只能有一个顶级类。例外:,该文件中可没有package-info类。类成员顺序类成员的顺序对代码的易读性有很大影响,但这也不存在唯一的通用法则。不同的类可能有不同的排序方式。重要的是,每个

6、类都要按照一定的逻辑规律排序。维护者应该要能解释这种排序 逻辑。比如,新的方法不能总是习惯性地添加到类的结尾,因为这样就是按时间顺序而非某种逻辑来排序的。重载方法:不应该分开当一个类有多个构造函数,或者多个同名成员方法时,这些函数应该写在一起, 不应该被其他成员分开。四、格式术语说明:块状结构(block-like construct )指类、成员函数和构造函数的实 现部分(大括号中间部分)。注意,在后面的节中讲到数组初始化,所有的数组 初始化都可以被认为是一个块状结构(非强制)。大括号不可省略大括号一般用在if ,? else ,?for ,?do和while等语句。即使当它的实现为空或者只

7、 有一句话时,也需要使用。非空语句块采用K&R风格对于非空语句块,大括号遵循 Kernighan & Ritchie 风格:左大括号前不换行。左大括号后换行。右大括号前换行。如果右大括号结束一个语句块或者函数体、构造函数体或者有命名的类体,则右大括号后换行,否则不要换行。仞0口,当右大括号后面接else或者逗号时,不应该换行。例子:1.2.3.4.5.6.return new MyClass () Override public if (condition try someting catchvoid method () ()();(ProblemException e ) 7

8、.recover();8. 9. 10. 11. ;一些例外的情况,将在节讲枚举类型的时候讲到空语句块:可以用简洁版本一个空的语句块,大括号可以简洁地写成匕不需要换行。如果它是一个多块语 句的一部分(if/else 或try/catch/finally ),即使大括号内没内容,右大括号也 要换行。例子:1. void doNothing () 语句块的缩进:4空格每当一个新的语句块产生,缩进就增加两个空格。当这个语句块结束时,缩进恢 复到上一层级的缩进格数。缩进要求对整个语句块中的代码和注释都适用。 (例 子可参考之前节中的例子)。一行最多只有一句代码每句代码的结束都需要换行。行长度限制:80

9、或100不同的项目可以选择采用80个字符或者100个字符作为限制。除了以下几个特 殊情况外,其他代码内容都需要遵守这个长度限制。这在节会有详细解释。例外:?1 .按照行长度限制,无法实现地方(例如:Javadoc中超长的URL地址,或 者一个超长的JSNI方法的引用);?2 .? package和import语句不受长度限制。(见、节);?3 .注释中的命令行指令行,将被直接复制到 shell中执行的。换行术语说明:当一行代码按照其他规范都合法,只是为了避免超出行长度限制而换 行时,称为长行断行。长行断行,没有一个适合所有场景的全面、确定的规范。但很多相同的情况,我们经常使用一些行之有效的断行

10、方法。注意:将长行封装为函数,或者使用局部变量的方法,也可以解决一些超出行长度限制的情况。并非一定要断行。在何处断行断行的主要原则是:选择在更高一级的语法逻辑的地方断行。其他一些原则如下:?1 .在一个逗号后面断开。2 .在一个操作符前面断开?(二号和foreach语句的冒号除外)。3 .在调用函数或者构造函数需要断行时,与函数名相连的左括号要在一行。也就是在左括号之后断行。?断行的缩进:至少8个字符当断行之后,在第一行之后的行,我们叫做延续行。每一个延续行在第一行的基础上至少缩进四个字符。?当原行之后有多个延续行的情况,缩进可以大于8个字符。如果多个延续行之问 由同样的语法元素断行,它们可以

11、采用相同的缩进。节介绍水平对齐中,解决了使用多个空格与之前行缩进对齐的问题。空白垂直空白以下情况需使用一个空行:1. 类成员之间需要空行隔开: 字段、构造函数、方法、内部类、静态初始化语句块(staticinitializers )、实例初始化语句块(instance initializers )。 ?o例外:连续字段之间的空白行不是必需的。一般多个字段中间的空行,是为了对字段做逻辑上的分组。2. 在函数体内,语句的逻辑分组间使用空行。3. 类的第一个成员之前,或者最后一个成员结束之后,用空行间隔。(可选)4. 本文档中其他部分介绍的需要空行的情况。(例如节中的import 语句) 单空行时使

12、用多行空行是允许的,但是不要求也不鼓励。水平空白除了语法和规范的其他规则,词语分隔、注释和 Javadoc外,水平的ASCII空 格只在以下情况出现:1. 所有保留的关键字与紧接它之后的位于同一行的左括号()之间需要用空格隔开。(例如?if、for、catch )2. 所有保留的关键字与在它之前的右大括号()之间需要空格隔开。(例如else、catch )3. 在左大寸号()之前都需要空格隔开。只有两种例外:?oSomeAnnotation(a, b)oString叩 x = "foo"4. 所有的二元运算符和三元运算符的两边,都需要空格隔开。一元操作符和操作数之间不应该加

13、空格,比如:负号 (“-”),自增(“+”)和自减(“-”)。例:i+;5. 逗号、冒号、分号和右括号之后。1. 如果在一条语句后做注释,则双斜杠.例外:?1.如果注解只有一个,并且不带参数。则它可以和类或方法名放在同一行。例如:Override public int hashCode () . 注解应用到字段时,也是紧接Javadoc之后。不同的是,多个注解可以放在同一 行。例如:1. Partial MockDataLoader loader ;对于参数或者局部变量使用注解的情况,没有特定的规范。注释语句块的注释风格注释的缩进与它所注释的代码缩进相同。 可以采用/*/进行注释,也可以用.

14、进行注释。当使用?/* .,进行多行注释时,每一行都应该以*开始,并且* 应该上下对齐。?注意文字和注释符之间有一个空格(水平空白)。例如:1. /*2. * This is* even do this. */3. */提示:多行注释时,如果你希望集成开发环境能自动对齐注释,你应该使用?/* .*/,. 一般不会自动对齐。修饰符多个类和字段的修饰符,按?Java Language Specification?»中介绍的先后顺序排序。具体是:1. public protected private abstract static final transient volatile sy n

15、chronized native strictfp数字型的字面值10ng类型的字面值使用大写L为后缀,永远不要使用小写l (避免和1混淆)例如:00L五、命名适用于所有命名标识符的通用规范标示符只应该使用ASCII字母、数字,字母大小写敏感。因此所有的标示符,都 应该能匹配正则表达式w+?。?标示符不需要使用特殊的前缀或后缀,如 name_ mName s_name和kName, 在Java编程风格中都不再使用。不同类型的标示符规范包名包名全部用小写字母,将各单词简单地连在一起(不使用下划线)。例如:,不 要使用或。类名类名都以UpperCamelCaseM格编写。?类名一般使用名词或名词短语

16、, 例如:Character或ImmutableList。接口名称一般 也使用名词或名词短语(如:List ),有时也可以使用形容词或形容词短语(如: Readable )。还没有特定的规则或行之有效的约定来命名注解类型。测试类的命名,应该以它所测试的类的名字为开头,并在最后加上 Test结尾。例如:HashTest?、HashIntegrationTest 。方法名方法名都以lowerCamelCase风格编写。?方法命名一般使用动词或者动词短语,例如:sendMessage或stop。在JUnit的测试方法中,可以使用下划线,用来区分逻辑组件的名字,经常使用如下的结构:test<Me

17、thodUnderTest>_<state> 。例如:testPop_emptyStack。?并不 存在唯一正确的方式来命名测试方法。常量名常量命名,全部使用大写字符,词与词之间用下划线隔开。( CONSTANCE_CASE常量的定义:每个常量都是一个静态final字段,但不是所有静态final字段都 是常量。在决定一个字段是否是一个常量时,考虑它是否真的感觉像是一个常量。例如,如果任何一个该实例的观测状态是可变的,则它几乎肯定不会是一个常量。只是永远不打算改变对象一般是不够的,它要真的一直不变才能将它示 为常量。下面是常量和非常量的例子:1. ();StaticMethod

18、 ();2. */3. public int method (String pl ) 或者为单行格式:1./* An especially short bit of Javadoc. */通用格式在任何时候使用都是可以的。当 Javadoc块只有一行时,可以使用单 行格式来替代通用格式。段落空白行:是指Javadoc中,上下两个段落之间只有上下对齐的*字符的行。每个段落的第一行在第一个字符之前,有一个p标签,并且之后不要有任何空格。Javadoc 标记所有标准的Javadoc标记,应该按照如下的顺序添加: param return、throws、 deprecated。并且如果这四种Javadoc标记出现,描述都不能为空。? 当刨句无法在一行写完时,应该断行。延续行在第一行的 ®符的位置,缩进至 少4个字符单位。摘要片段每个类或者成员的Javadoc,都是由一个摘要片段开始的。这个片段非常重要。 因为它是类或者方法在使用时唯一能看到的文本说明。?主要摘要只是一个片段,应该是一个名词短语或者动词短语, 而不应该是一个完 整的句子。不应该以类似于: A code Foo is a. 或This method returns. 这样 的开头,

温馨提示

  • 1. 本站所有资源如无特殊说明,都需要本地电脑安装OFFICE2007和PDF阅读器。图纸软件为CAD,CAXA,PROE,UG,SolidWorks等.压缩文件请下载最新的WinRAR软件解压。
  • 2. 本站的文档不包含任何第三方提供的附件图纸等,如果需要附件,请联系上传者。文件的所有权益归上传用户所有。
  • 3. 本站RAR压缩包中若带图纸,网页内容里面会有图纸预览,若没有图纸预览就没有图纸。
  • 4. 未经权益所有人同意不得将文件中的内容挪作商业或盈利用途。
  • 5. 人人文库网仅提供信息存储空间,仅对用户上传内容的表现方式做保护处理,对用户上传分享的文档内容本身不做任何修改或编辑,并不能对任何下载内容负责。
  • 6. 下载文件中如有侵权或不适当内容,请与我们联系,我们立即纠正。
  • 7. 本站不保证下载资源的准确性、安全性和完整性, 同时也不承担用户因使用这些下载资源对自己和他人造成任何形式的伤害或损失。

评论

0/150

提交评论