`
isiqi
  • 浏览: 15948321 次
  • 性别: Icon_minigender_1
  • 来自: 济南
社区版块
存档分类
最新评论

java编码规范_缩进和注释

阅读更多

1. 缩进排版(Indentation)

4个空格常被作为缩进排版的一个单位。缩进的确切解释并未详细指定(空格 vs. 制表符)。一个制表符等于n个空格(视具体的编辑器而定,Eclipse默认一个制表符为4个字符)

3.1 行长度(Line Length)

尽量避免一行的长度超过80个字符,因为很多终端和工具不能很好处理之。

注意:鉴于Eclipse开发工具工作区的左侧和右侧都被非代码编辑器所占据,因此建议每行的代码长度不要超过70个字符。

3.2 换行(Wrapping Lines)

当一个表达式无法容纳在一行内时,可以依据如下一般规则断开之:

·在一个逗号后面断开;

·在一个操作符前面断开;

·宁可选择较高级别(higher-level)的断开,而非较低级别(lower-level)的断开;

·新的一行应该与上一行同一级别表达式的开头处对齐。

·如果以上规则导致你的代码混乱或者使你的代码都堆挤在右边,那就代之以缩进8个空格,或者以调用参数的首个括号对齐,或者以首个运算法对齐。

以下是断开方法调用的一些例子:

someMethod(longExpression1, longExpression2, longExpression3, longExpression4,

longExpression5);

var = someMethod1(longExpression1,

someMethod2(longExpression2, longExpression3));

以下是两个断开算术表达式的例子。前者更好,因为断开处位于括号表达式的外边,这是个较高级别的断开。

longName1 = longName2 * ( longName3 + longName4 - longName5 ) +

4 * longname6; //推荐使用

longName1 = longName2 * ( longName3 + longName4

- longName5 ) + 4 * longname6; //应避免这样使用

以下是两个缩进方法声明的例子。前者是常规情形。后者若使用常规的缩进方式将会使第二行和第三行移得很靠右,所以代之以缩进空格,尽量与运算符或者括号对齐。

//CONVENTIONAL INDENTATION

someMethod(int anArg, Object anotherArg, String yetAnotherArg,

Object andStillAnother) {

...

}

//INDENT 8 SPACES TO AVOID VERY DEEP INDENTS

private static synchronized horkingLongMethodName(int anArg,

Object anotherArg, String yetAnotherArg, Object andStillAnother) {

...

}

if语句的换行通常使用8个空格的规则,因为常规缩进(4个空格)会使语句体看起来比较费劲。比如:

//DON’T USE THIS INDENTATION

if ((condition1 && condition2)

|| (condition3 && condition4)

||!(condition5 && condition6)) { //BAD WRAPS

doSomethingAboutIt(); //MAKE THIS LINE EASY TO MISS

}

//USE THIS INDENTATION INSTEAD

if ((condition1 && condition2)

|| (condition3 && condition4)

||!(condition5 && condition6)) {

doSomethingAboutIt();

}

//OR USE THIS

if ((condition1 && condition2) || (condition3 && condition4)

||!(condition5 && condition6)) {

doSomethingAboutIt();

}

这里有三种可行的方法用于处理三元运算表达式:

alpha = (aLongBooleanExpression) ? beta : gamma; //表达式代码不长时,应尽量使用该方法

alpha = (aLongBooleanExpression) ? beta //表达式代码较长时可以使用该法

: gamma;

alpha = (aLongBooleanExpression) //表达式代码较长时也可以使用该法

? beta

: gamma;

2. 注释(Comments)

Java程序有两类注释:实现注释(implementation comments)和文档注释(document comments)。实现注释是那些在C++中见过的,使用/*...*///界定的注释。文档注释是Java独有的,并由/**...*/界定。文档注释可以通过javadoc工具转换成HTML文件。

实现注释用以注释代码或者实现细节。文档注释从实现自由(implementation-free)的角度描述代码的规范。它可以被那些手头没有源码的开发人员读懂。

注释应被用来给出代码的总括,并提供代码自身没有提供的附加信息。注释应该仅包含与阅读和理解程序有关的信息。例如,相应的包如何被建立或位于哪个目录下之类的信息不应包括在注释中。

在注释里,对设计决策中重要的或者不是显而易见的地方进行说明是可以的,但应避免提供代码中己清晰表达出来的重复信息。通常应避免那些代码更新就可能过时的注释。

注意:频繁的注释有时反映出代码的低质量。当你觉得被迫要加注释的时候,考虑一下重写代码使其更清晰。

注释不应写在用星号或其他字符画出来的大框里。注释不应包括诸如制表符和回退符之类的特殊字符。

4.1 实现注释的格式(Implementation Comment Formats)

程序可以有4种实现注释的风格:块(block)、单行(single-line)、尾端(trailing)和行末(end-of-line)

4.1.1 块注释(Block Comments)

块注释通常用于提供对文件,方法,数据结构和算法的描述。块注释被置于每个文件的开始处以及每个方法之前。它们也可以被用于其他地方,比如方法内部。在功能和方法内部的块注释应该和它们所描述的代码具有一样的缩进格式。

块注释之首应该有一个空行,用于把块注释和代码分割开来,比如:

/*

* Here is a block comment.

*/

块注释可以以/*-开头,这样indent(1)就可以将之识别为一个代码块的开始,而不会重排它。

/*-

* Here is a block comment with some very special

* formatting that I want indent(1) to ignore.

*

* one

* two

* three

*/

注意:如果你不使用indent(1),就不必在代码中使用/*-,或为他人可能对你的代码运行indent(1)作让步。

4.1.2 单行注释(Single-Line Comments)

短注释可以显示在一行内,并与其后的代码具有一样的缩进层级。如果一个注释不能在一行内写完,就该采用块注释(参见块注释”)。单行注释之前应该有一个空行。以下是一个Java代码中单行注释的例子:

if (condition) {

/* Handle the condition. */

...

}

4.1.3 尾端注释(Trailing Comments)

极短的注释可以与它们所要描述的代码位于同一行,但是应该有足够的空白来分开代码和注释。若有多个短注释出现于大段代码中,它们应该具有相同的缩进。

以下是一个Java代码中尾端注释的例子:

if (a == 2) {

return TRUE; /* special case */

} else {

return isPrime(a); /* works only for odd a */

}

4.1.4 行末注释(End-Of-Line Comments)

注释界定符"//",可以注释掉整行或者一行中的一部分。它一般不用于连续多行的注释文本;然而,它可以用来注释掉连续多行的代码段。以下是所有三种风格的例子:

if (foo > 1) {

// Do a double-flip.

...

}

else {

return false; // Explain why here.

}

//if (bar > 1) {

//

// // Do a triple-flip.

// ...

//}

//else {

// return false;

//}

4.2 文档注释(Documentation Comments)

注意:此处描述的注释格式之范例,参见"Java源文件范例"

若想了解更多,参见"How to Write Doc Comments for Javadoc",其中包含了有关文档注释标记的信息(@return, @param, @see)http://java.sun.com/javadoc/writingdoccomments/index.html

若想了解更多有关文档注释和javadoc的详细资料,参见javadoc的主页: http://java.sun.com/javadoc/index.html

文档注释描述Java的类、接口、构造器,方法,以及字段(field)。每个文档注释都会被置于注释定界符/**...*/之中,一个注释对应一个类、接口或成员。该注释应位于声明之前:

/**

* The Example class provides ...

*/

public class Example { ...

注意顶层(top-level)的类和接口是不缩进的,而其成员是缩进的。描述类和接口的文档注释的第一行(/**)不需缩进;随后的文档注释每行都缩进1(使星号纵向对齐)。成员,包括构造函数在内,其文档注释的第一行缩进4格,随后每行都缩进5格。

若你想给出有关类、接口、变量或方法的信息,而这些信息又不适合写在文档中,则可使用实现块注释或紧跟在声明后面的单行注释。例如,有关一个类实现的细节,应放入紧跟在类声明后面的实现块注释中,而不是放在文档注释中。

文档注释不能放在一个方法或构造器的定义块中,因为Java会将位于文档注释之后的第一个声明与其相关联。

分享到:
评论

相关推荐

    java编码规范(命名规范、注释规范、缩进排版规范、文件名规范、声明规范、语句规范以及编程规范)

    Java开发中所要遵守的编码规范大体上有如下7点。命名规范、注释规范、缩进排版规范、文件名规范、声明规范、语句规范以及编程规范。

    Java经典编程规范,参考京东和华为的Java编程规范标准,将两家公司共同拥有的规范提取并整理得出,值得收藏

    本文档从“Java编程代码规范”,“Java编程注释规范”,“Java编程命名规范”,“代码缩进/断行/空行/空格/大括号规范”,“日志记录规范”和“代码上库规范”六个方面提取两家公司的Java编程规范共性。希望能供Java...

    Java语言编码规范

    Java语言编码规范 1 介绍(INTRODUCTION) 3 1.1 为什么要有编码规范(WHY HAVE CODE CONVENTIONS) 3 1.2 版权声明(ACKNOWLEDGMENTS) 3 2 文件名(FILE NAMES) 4 2.1 文件后缀(FILE SUFFIXES) 4 2.2 常用文件名(COMMON ...

    JAVA编码规范(2012版)

    JAVA编程规范2012年本公司自编。 1.命名规范 4 1.1. 共通事項 4 1.2. 方法(函数)的命名 4 1.3. 字段与局部变量的命名 5 1.4. 命名实例 5 2.方法 6 2.1. JavaDoc注释方法 6 2.2. 起始注释的记述方法 7 2.3. 其它...

    Java编码规范

    这个ppt主要是为开发人员规范代码提供手册,其中包含漂亮的代码是什么样子、编码规范的原则、标识符命名、空格、空行和缩进、注释及最佳实践和禁忌等内容。

    Java 高手编码规范(初)

    Java 编码规范,养成良好编码习惯。 ---------------------------- 统一编码风格、提高代码质量。 ----------------------------  除字符串和注释内以外, 代码中的空格一律为半角。  代码中不应有[TAB]字符(除...

    Java语言编码规范[含书签]

    3.1 Java源文件 o 3.1.1 开头注释 o 3.1.2 包和引入语句 o 3.1.3 类和接口声明 4 缩进排版 ? 4.1 行长度 ? 4.2 换行 5 注释 ? 5.1 实现注释的格式 o 5.1.1 块注释 o 5.1.2...

    Java语言编码规范(Java Code Conventions) txt版

    4 缩进排版(Indentation) 5 注释(Comments) 6 声明(Declarations) 7 语句(Statements) 8 空白(White Space) 9 命名规范(Naming Conventions) 10 编程惯例(Programming Practices) 11 代码范例(Code Examples) 花点...

    6. 编码规范1

    2.注释规范(1)注释尽可能使用“//” 3.缩进排版规范(1)避免一行的长度超过 60 个字符 4.文件名规范(1)一个 Java 源文件只能存储一个 Jav

    Android开发规范

    Android内部开发规范,编码规范 目录 1 介绍 5 1.1 目的 5 1.2 术语和定义 5 2 文件组织 5 2.1 JAVA包和源文件 5 2.1.1 开头注释 5 2.1.2 包和引入语句 6 2.1.3 类和接口声明 6 3 缩进排版 7 3.1 行长度 7 3.2 括号 ...

    word源码java-COMP603_Project:COMP603_项目

    编码规范 缩进 采用设置4个空格的缩进方式。 换行 一行不超过75个字符 如果太长,可以在:“,”后换行,或者运算符前换行 空格 在关键字和()之间加空格,如:while () 运算符前后加空格 在参数列表的“,”后加空格...

    ZendFramework中文文档

    3.3.2. 规范(Specifics) 3.3.3. 身份(Identity) 3.4. HTTP 认证适配器 3.4.1. 简介 3.4.2. 设计回顾 3.4.3. 配置选项 3.4.4. Resolvers 3.4.4.1. 文件 Resolver 3.4.5. 基本用法 4. Zend_Cache 4.1. ...

Global site tag (gtag.js) - Google Analytics