JAVA代码规范笔记(上)

简介: 本文为《code conventions-150003》(JAVA代码规范)笔记。 文件组织 1、超过2000行代码的源文件将会比较难以阅读,应该避免。 2、每个Java源文件都包含单一的公共类或接口。

本文为《code conventions-150003》(JAVA代码规范)笔记。


文件组织

1、超过2000行代码的源文件将会比较难以阅读,应该避免。

2、每个Java源文件都包含单一的公共类或接口。如果私有类和接口与一个公共类有联系,可以把它们与这个公共类放在同一个源文件中。公共类必须是文件中的第一个类或接口。

3、JAVA源文件内容应该遵循以下顺序:

  • 开头注释
  • 包声明和引入语句,如:

import java.applet.Applet;
import java.awt.*;
import java.net.*;

  • 类和接口的声明
4、开头注释
     所有的源文件在开头应该有一个C语言风格的注释,列出作者、日期和版权声明,并对程序的目的有一个简要的描述。例如:
/*
 *Classname
 *
 *Version info
 *
 *Copyright notice
 */

5、包声明和引入语句
    大多数Java源文件的第一条非注释语句都是包声明语句,接着是引入语句。如下:
package java.awt;
import java.awt.peer.CanvasPeer;

6、类和接口声明
下表描述了类和接口声明的各个部分,以及它们出现的顺序。
  类/接口声明的各部分 备注
1 类/接口的文档注释 该注释所需包含的信息可以参见下面的文档注释
2 类/接口的声明  
3 类/接口的实现注释(/*...*/),如果有必要的话 该注释应该包含所有与类或接口有关的信息,而这些信息又不适合作文档注释。
4 类(静态)变量 首先是类的公有(public)变量,然后是保护(protected)变量,之后是私有(private)变量。
5 实例变量 首先是公有的(public),接着是保护的(protected),之后是私有的(private)。
6 构造方法  
7 方法 这些方法应该按功能,而非作用域或访问权限来分组。例如,一个私有的类方法可以在两个公有的实例方法之间,其目的是为了更利于代码的阅读与理解。

缩进
7、通常4个空格被作为缩进的一个单位。缩进使用的具体结构(是空格还是制表符)并无指明。一个制表符相当于8个空格(而非4个)。
8、行长度。
    避免一行代码超过80字符。因为它们在许多终端或工具都无法被很好的处理。
    注意:在文档中的例子行长度应该更短,一般不超过70字符。
9、换行
    当一条语句无法在一行写完,可以根据下面的一般原则来断句:
  • 在一个逗号后断开
  • 在一个操作符前断开
  • 高级别的断开优先于低级别的断开
  • 新的一行应该与上一句同一级别表达式的开头处对齐
  • 如果以上的规则导致代码混乱,或使代码都堆挤在右边,可以代之以8个空格的缩进。
    下面是断开方法调用的一些例子:
function(longExpression1, longExpression2, longExpression3,
         longExpression4, longExpression5);
var = function1(longExpression1,
                function2(longExpression2,
                          longExpression3));

    下面两个例子是断开算术表达式的例子。第一个更好一点,因为断开处是在括号表达式外面,它是个较高级别的断开。
longName1 = longName2 * (longName3 + longName4 - longName5)
            + 4 * longname6; // PREFER
longName1 = longName2 * (longName3 + longName4
                         - longName5) + 4 * longname6; // AVOID
    下面是两个方法声明的缩进例子。第一个例子是常规情况。而第二个例子,如果使用常规的缩进方式,它会使第二行和第三行的代码太过于偏右,所以以缩进8个空格的方式代替。
//常规缩进
someMethod(int anArg, Object anotherArg, String yetAnotherArg,
           Object andStillAnother) {
    ...
}
//以8个空格来代替,以避免缩进太严重
private static synchronized horkingLongMethodName(int anArg,
        Object anotherArg, String yetAnotherArg,
        Object andStillAnother) {
    ...
}
    if语句的换行通常应该使用8个空格的规则,因为常规的缩进(使用4个空格)会使语句体比较难以阅读。例如:
//请勿使用这种缩进
if ((condition1 && condition2)
    || (condition3 && condition4)
    ||!(condition5 && condition6)) { //BAD WRAPS
    doSomethingAboutIt(); //MAKE THIS LINE EASY TO MISS
}
//使用这种缩进来代替
if ((condition1 && condition2)
        || (condition3 && condition4)
        ||!(condition5 && condition6)) {
    doSomethingAboutIt();
}
//或这种缩进
if ((condition1 && condition2) || (condition3 && condition4)
        ||!(condition5 && condition6)) {
    doSomethingAboutIt();
}

    下面是三种格式化三目表达式的可行方法。
alpha = (aLongBooleanExpression) ? beta : gamma;
alpha = (aLongBooleanExpression) ? beta
                                 : gamma;
alpha = (aLongBooleanExpression)
        ? beta
        : gamma;

注释
10、Java程序有两类注释:实现注释和文档注释。实现注释就是在那些C++代码中见到的,使用/*...*/和//来限定的注释。文档注释是Java独有的,使用/**...*/来限定的注释。文档注释可以通过javadoc工具来提取成HTML文件。
实现注释是用来解释代码或详细说明实现的。文档注释通过实现自由的角度,来描述代码的使用说明,它被那些没必要有源代码在手上的程序员阅读。
注释通常用来给出代码的概述,和提供从代码本身不易得到的附加信息。注释应该只包含与阅读理解程序相关的信息。例如,相应的包如何被创建,或者它位于哪个目录,这样的信息就不应该包含在注释中。
注意:太频繁的注释有时也可以反映出代码质量欠佳。当你感觉不得不加上一个注释时,考虑一下重写代码并它更清晰。
注释不应该被封闭在一个用星号或其他字符画成的大框里。注释永远都不应该包含像制表符或退格符这样的特殊字符。

11、实现注释
程序可以有四种风格的实现注释:块注释,单行注释,尾端注释和行末注释。

12、块注释
块注释通常用于提供文件、方法、数据结构和算法的描述。块注释应当用在每个文件的开头和每个方法的前面。它们也可以用在其他地方,例如方法内部。在函数或方法内部的注释,应该和他们描述的代码有同样级别的缩进。
块注释前面应该有一个空行,来将它与其他代码分离开。块注释除了第一行之外,每一行都以一个星号“*”开头。
/*
 * 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)作出其他的让步。

13、单行注释
短的注释可以出现在一行内,并与其后面的代码有一样的缩进层级。如果一个注释无法在一行内写完,就应该使用块注释格式。一个单行注释前应该有一个空行。下面是Java代码里的单行注释的例子:
if (condition) {

    /* Handle the condition. */
    ...
}

14、尾端注释
非常短的注释可以出现在其描述的代码的同一行,但应该有足够的空白来分开代码与注释。如果有超过一个的短注释出现在一大块代码中,它们应该被缩进到同一个tab setting中(不会翻译,原文是they should all be indented to the same tab setting,大概意思是缩进到这些注释能对齐)。避免在每一行可执行代码都加上一个尾端注释的这种汇编语言风格的注释。
下面是Java代码尾端注释的一个例子:
if (a == 2) {
    return TRUE;            /* special case */
} else {
    return isprime(a);      /* works only for odd a */
}

15、行末注释
注释分隔符“//”开头的是不断换行的注释。它可以用来注释掉整行或一行中的一部分。它一般不用于连续多行的文本注释,但可以被用来注释掉连续多行的代码段。下面是所有三种风格的例子:
if (foo > 1) {
    // Do a double-flip.
    ...
}
else
    return false; // Explain why here.

//if (bar > 1) {
//
//    // Do a triple-flip.
//    ...
//}
//else
//    return false;

16、文档注释
若想了解更多详情,参见“How to Write Doc Comments for Javadoc”,其中包含了文档注释标记的信息(@return,@param,@see):
http://java.sun.com/products/jdk/javadoc/writingdoccomments.html
关于文档注释和javadoc的更多信息,参见javadoc主页:
http://java.sun.com/products/jdk/javadoc/

文档注释描述Java的类、接口、构造器、方法和字段。每个文档注释都置于注释分隔符/**...*/中,每个API对应一个注释。这个注释应该只出现在声明之前:
/**
 * The Example class provides ...
 */
class Example { ...

注意类和接口是不缩进的,而它的成员是缩进的。类和接口的文档注释的第一行(/**)是不缩进的,其后的文档注释行的都各有一个空格的缩进(使星号垂直对齐)。成员,包括构造方法,其文档注释的第一行是4个空格的缩进,其后是缩进5个空格。
如果你需要给出有关类、接口、变量或方法的信息,而这些信息又不适合出现在文档中,可以在紧跟在声明之后使用块注释或单行注释。例如一个类实现的细节,就应该在紧跟在类声明之后的块注释中,而不是在这个类的文档注释中。
文档注释不应该被放在方法或构造器的定义块中,因为Java会将文档注释与其后面的第一个声明进行关联。
目录
相关文章
|
22天前
|
Java 索引
Java实现扑克牌游戏 | 随机发牌 ( 过程拆分详解+完整代码 )
Java实现扑克牌游戏 | 随机发牌 ( 过程拆分详解+完整代码 )
|
13天前
|
Java 程序员 API
Java中的Lambda表达式:简化你的代码
【7月更文挑战第10天】Lambda表达式,这一Java 8的闪亮特性,为开发者提供了一种更为简洁、灵活的编程方式。本文将探讨Lambda表达式如何优化代码结构,提升开发效率,以及在实际项目中应用的一些实例。我们将从基础语法入手,逐步深入到高级用法,最后讨论其性能影响,旨在帮助读者全面理解并有效利用Lambda表达式。
36 20
|
2天前
|
JSON Java BI
一次Java性能调优实践【代码+JVM 性能提升70%】
这是我第一次对系统进行调优,涉及代码和JVM层面的调优。如果你能看到最后的话,或许会对你日常的开发有帮助,可以避免像我一样,犯一些低级别的错误。本次调优的代码是埋点系统中的报表分析功能,小公司,开发结束后,没有Code Review环节,所以下面某些问题,也许在Code Review环节就可以避免。
43 0
一次Java性能调优实践【代码+JVM 性能提升70%】
|
6天前
|
存储 缓存 JavaScript
|
24天前
|
Java Spring
JAVA注解:传统与现代的完美结合,你的代码值得拥有!
【6月更文挑战第29天】Java注解,作为连接传统与现代的编程工具,简化企业级应用开发,提升代码可读性和维护性。通过自定义注解如`@Loggable`,可以将行为(如日志记录)与方法实现分离,减少模板代码。使用AOP(如Spring)处理注解,实现行为拦截,增强代码灵活性和可扩展性。拥抱Java注解,让代码更现代、更高效!
38 16
|
14天前
|
监控 Java Maven
使用AspectJ实现Java代码的运行时织入
使用AspectJ实现Java代码的运行时织入
|
19天前
|
缓存 算法 安全
|
6天前
|
SQL Java 数据处理
实时计算 Flink版产品使用问题之使用MavenShadePlugin进行relocation并遇到只包含了Java代码而未包含Scala代码,该怎么办
实时计算Flink版作为一种强大的流处理和批处理统一的计算框架,广泛应用于各种需要实时数据处理和分析的场景。实时计算Flink版通常结合SQL接口、DataStream API、以及与上下游数据源和存储系统的丰富连接器,提供了一套全面的解决方案,以应对各种实时计算需求。其低延迟、高吞吐、容错性强的特点,使其成为众多企业和组织实时数据处理首选的技术平台。以下是实时计算Flink版的一些典型使用合集。
|
11天前
|
Java 编译器 API
Java中的Lambda表达式:简化代码,提升性能
在Java 8中,Lambda表达式的引入为开发者提供了一种更加简洁、灵活的编程方式。本文将深入探讨Lambda表达式的概念、语法、使用场景及其在Java中的应用示例,帮助读者更好地理解和掌握这一强大工具,从而优化代码结构,提高开发效率。
|
15天前
|
监控 Java Maven
使用AspectJ实现Java代码的运行时织入
使用AspectJ实现Java代码的运行时织入