JAVA代码规范笔记(上)-阿里云开发者社区

开发者社区> 浩码农> 正文

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会将文档注释与其后面的第一个声明进行关联。

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

相关文章
【Java学习笔记之二】java标识符命名规范
什么是标识符 就是程序员在定义java程序时,自定义的一些名字。标识符可以应用在类名、变量、函数名、包名上。   标识符必须遵循以下规则 标识符由26个英文字符大小写(a~zA~Z)、数字(0~9)、下划线(_)和美元符号($)组成。
891 0
《区块链DAPP开发入门、代码实现、场景应用》笔记5——区块链福利彩票的设计
笔者一直强调,一定要利用区块链的特点来解决行业存在的问题,并且该问题最好用区块链解决或者说只能用区块链解决。彩票行业就是个例子。
1631 0
Java 7: 全面教程-1.2 Java代码规格
写正确的可运行的Java程序固然重要,但是写出的代码方便阅读和维护也是相当重要的。普遍相信一个软件80%的时间都花在维护上。而且,程序员的变动率非常的高,所以很有可能是别人在维护你的代码。如果你留下的程序源代码是清楚且简单易懂的,不管是谁都会非常感谢你。
1167 0
编写高质量的 Java 代码
代码质量概述 代码质量所涉及的5个方面,编码标准、代码重复、代码覆盖率、依赖项分析、复杂度分析。这5方面很大程序上决定了一份代码的质量高低。 我们分别来看一下这5方面:编码标准:这个想必都很清楚,每个公司几乎都有一份编码规范,类命名、包命名、代码风格之类的东西都属于其中。
775 0
阿里云服务器端口号设置
阿里云服务器初级使用者可能面临的问题之一. 使用tomcat或者其他服务器软件设置端口号后,比如 一些不是默认的, mysql的 3306, mssql的1433,有时候打不开网页, 原因是没有在ecs安全组去设置这个端口号. 解决: 点击ecs下网络和安全下的安全组 在弹出的安全组中,如果没有就新建安全组,然后点击配置规则 最后如上图点击添加...或快速创建.   have fun!  将编程看作是一门艺术,而不单单是个技术。
4441 0
JavaScript 代码规范
所有的 JavaScript 项目适用同一种规范 ## JavaScript 代码规范 代码规范通常包括以下几个方面: 变量和函数的命名规则 空格,缩进,注释的使用规则 其他常用规范…… 规范的代码可以更易于阅读与维护 代码规范一般在开发前规定,可以跟你的团
8745 0
java代码调用oracle存储过程
一、简介   与调用mysql存储过程类型过程都是如下   1、创建连接 Connection conn = DriverManager.getConnection(url, user, password);   2、创建CallableStatement CallableStatement statement = conn.
679 0
怎样编写高质量的java代码
怎样编写高质量的java代码 怎样辨别一个项目代码写得好还是坏?优秀的代码和腐化的代码区别在哪里?怎么让自己写的代码既漂亮又有生命力?接下来将对代码质量的问题进行一些粗略的介绍。也请有过代码质量相关经验的朋友提出宝贵的意见。
1282 0
《区块链DAPP开发入门、代码实现、场景应用》笔记4——Ethereum Wallet中部署合约
账号创建完成之后,账号余额是0,但是部署合约是需要消耗GAS的,因此需要获取一定的以太币才能够继续本次实现。
1458 0
+关注
浩码农
开源社区技术专家
167
文章
0
问答
文章排行榜
最热
最新
相关电子书
更多
文娱运维技术
立即下载
《SaaS模式云原生数据仓库应用场景实践》
立即下载
《看见新力量:二》电子书
立即下载