Java编码规范

Java编码规范

　 本文讲述了Java语言的编码规范，也是我多年书写java代码的总结。其中借鉴了oracle官方的java规范，并且结合现代互联网企业对java代码的要求，以及自己在代码书写过程中的感悟。尽量做到使代码美观，易读，易维护。由于美观，易读的代码有很多种形式，所以我只介绍我使用的形式。其实对于公司或者团队来说，也只需要一种，也只能是其中一种。当然有些简单，大家一直在使用的规律，可能不会全部写出来，可以直接看官方文档。

• 缩进
• 注释
• 声明
• 语句
• 命名规范
• 代码范例

---

1. 缩进

   1. 4个空格常被作为缩进排版的一个单位。缩进的确切解释并未详细指定(空格 vs. 制表符)。一个制表符等于8个空格(而非4个)。
   2. 尽量避免一行的长度超过80个字符，因为很多终端和工具不能很好处理。

   3. 当一个表达式无法容纳在一行时，可以依据以下规则断开

      • 在逗号后面断开
      • 在操作符前面断开
      • 宁可选择较高级别(higher-level)的断开，而非较低级别(lower-level)的断开
      • 新的一行应该与上一行同一级别表达式的开头处对齐
      • 如果以上规则导致你的代码混乱或者使你的代码都堆挤在右边，那就代之以缩进8个空格。

      function(longExpression1, longExpression2, longExpression3,
       longExpression4, longExpression5);
      
      var = function1(longExpression1,
                     function2(longExpression2,
                               longExpression3));

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

   在注释里，对设计决策中重要的或者不是显而易见的地方进行说明是可以的，但应避免提供代码中己清晰表达出来的重复信息。多余的的注释很容易过时。

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

   块注释

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

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

   
         /*
                   * Here is a block comment.
                   */

   单行注释

   单行注释(Single-Line Comments)。单行注释之前应该有一个空行。以下是一个Java代码中单行注释的例子：

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

     if (a == 2) {
               return TRUE;              /* special case */
               } else {
               return isPrime(a);         /* works only for odd a */
               }

   文档注释

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

     /**
               * The Example class provides ...
               */
               public class Example { ...

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

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

3. 声明(Declarations)

   • 每行只声明一个变量（方便注释）
   • 尽量在声明局部变量的同时初始化,如int i=0;唯一不这么做的理由是变量的初始值依赖于某些先前发生的计算
   • 只在代码块的开始处声明变量(否则会妨碍代码在该作用域内的可移植性)

     void myMethod() {
               int int1 = 0;         // beginning of method block
               if (condition) {
               int int2 = 0;     // beginning of "if" block
               ...
               }
               }

   • 在方法名与其参数列表之前的左括号”(“间不要有空格
   • 左大括号”{“位于声明语句同行的末尾
   • 右大括号”}”另起一行，与相应的声明语句对齐，除非是一个空语句，”}”应紧跟在”{“之后

     class Sample extends Object {
               int ivar1;
               int ivar2;
               Sample(int i, int j) {
               ivar1 = i;
               ivar2 = j;
               }
               int emptyMethod() {}
               ...
               }

   • 方法与方法之间以空行分隔

   • 注意：if语句总是用”{“和”}”括起来，避免使用如下容易引起错误的格式：

   if (condition) //AVOID! THIS OMITS THE BRACES {}!
               statement;

4. 命名规范(Naming Conventions)

   包(Packages)
   一个唯一包名的前缀总是全部小写的ASCII字母并且是一个顶级域名，通常是com，edu，gov，mil，net，org。包名的后续部分根据不同机构各自内部的命名规范而不尽相同。这类命名规范可能以特定目录名的组成来区分部门(department)，项目(project)，机器(machine)，或注册名(login names)。
   com.sun.eng
   com.apple.quicktime.v2
   edu.cmu.cs.bovik.cheese
   类(Classes)
   类名是个一名词，采用大小写混合的方式，每个单词的首字母大写。尽量使你的类名简洁而富于描述。使用完整单词，避免缩写词(除非该缩写词被更广泛使用，像URL，HTML)
   class Raster;
   class ImageSprite;
   接口(Interfaces)
   大小写规则与类名相似
   interface RasterDelegate;
   interface Storing;
   方法(Methods)
   方法名是一个动词，第一个单词的首字母小写，其后单词的首字母大写。
   run();
   runFast();
   getBackground();
   变量(Variables)
   变量名应简短且富于描述。变量名的选用应该易于记忆，即，能够指出其用途。尽量避免单个字符的变量名，除非是一次性的临时变量。临时变量通常被取名为i，j，k，m和n，它们一般用于整型；c，d，e，它们一般用于字符型。
   char c;
   int i;
   float myWidth;
   全局变量(Global Variables)
   大小写规则和变量名相似，除了前面需要一个”m_” ,类似于C++
   String m_name;
   Customer m_customer;

   只有你看过很多的代码，很复杂的代码，你才知道知道一个变量是全局的重要性。然而很多程序员都不这样做

   常量(Constants)
   类常量和ANSI常量的声明，应该全部大写，单词间用下划线隔开。(尽量避免ANSI常量，容易引起错误)
   static final int MIN_WIDTH = 4;
   static final int MAX_WIDTH = 999;
   static final int GET_THE_CPU = 1;

5. 代码例子（Code Examples）

   /*
               *
               * Copyright (c) 1998-2016 glowd.
               * 2046 Century Road,WUHOU, CHENGDU,CHINA.
               * All rights reserved.
               */
               package com.glowd;
               import com.glowd.silver;
               /**
               * Class description goes here.
               *
               * @version  1.23 18 Mar 2016
               * @author   glowd
               */
               public class Glowd extends God{
                   /* A class implementation comment can go here. */
                   /** m_num documentation comment */
                   public static int m_num;
                   /**
                   * m_ideaPointdocumentation comment 
                   * that happens to be
                   * more than one line long
                   */
                   private static Object m_ideaPoint;
                   /** m_friend documentation comment */
                   public Object m_friend;
                   /** m_students documentation comment */
                   private Object[] m_students;
                   /**
                   * ...constructor glowd documentation comment...
                   */
                   public Glowd() {
                   // ...implementation goes here...
                   }
                   /**
                   * ...method doSomething documentation comment...
                   */
                   public void doSomething() {
                   // ...implementation goes here...
                   }
                   /**
                   * ...method doSomething Else documentation comment...
                   * @param someParam description
                   */
                   public void doSomethingElse(Object someParam) {
                   // ...implementation goes here...
                   }
               }