首页手记标准的Java编码规范手册

标准的Java编码规范手册

标签：

Android

编码规范体现出一个开发者的基本素质，良好的编码规范可以提高团队编码的效率，避免很多不必要的问题。今天分享一个标准的Java编码规范给大家，希望对于大家今后的开发工作带来帮助。

编码规范的意义

在项目开发维护中，编码规范作为开发规范的一个组成部分，是十分重要和必须的，它不仅仅是为了提高开发效率，也有利于降低后期维护开发的成本。编码规范的根本目的就是要让不仅代码可以一目了然，也可以很容易的理解开发人员所编写的代码程的用途和意义。由此，用来减少项目中因为开发维护人员的更替或由于长时间不维护造成的记忆模糊或混乱等情况带来的对代码所实现的真正功能的理解困难和歧义。另外也提高了代码复查效率和效果。

规范实施建议

不是为了规范而规范，以提高软件开发质量和效率为目标，辅以IDE等开发工具为保障，逐步改进编码规范化水平

对于格式规范、注释规范等部分规范的要求，可以通过使用eclipse/AndroidStudio自带的Format方法（快捷键：Ctrl+Shift+F）进行自动格式化，可以提高开发效率又符合编码规范。

编码规范文档本身需要定期不断的修正和完善，以符合实际开发规范的要求。

格式规范

a)缩进
使用配置文件进行格式化：
配置文件中一个TAB等于4个空格。

b)行长度
每行100字符
注：使用eclipse自带的Format方法（快捷键：Ctrl+Shift+F）时，需要配置“Maximum line width”设置长度为100

c)声明

d)声明变量、常量
一行只声明一个变量或常量；
在代码块的开始处声明实例变量，不要在首次用到该变量时才声明【推荐】

e)声明类
左大括号”{“位于声明语句同行的末尾，右大括号”}”另起一行；
方法与方法之间以空行分隔

f)语句
可以使用eclipse自带的Format方法（快捷键：Ctrl+Shift+F）时使用eclipse默认的“Control Statements ”格式化方法进行
注：if语句总是用”{“和”}”括起来
示例

class Example {
    void bar() {
        do {
        } while (true);
        try {
        } catch (Exception e) {
        } finally {
        }
    }

    void foo2() {
        if (true) {
            return;
        }
        if (true) {
            return;
        } else if (false) {
            return;
        } else {
            return;
        }
    }
}

g)空格的使用

等号左右必须各有一个空格：
button = null;
双目运算符左右必须各有一个空格：
imageWidth = imagePadding + imageSize;
标点符号后面必须跟一个空格
标点符号包括“,”、“;”等，下面列出几个例子。
一行定义多个变量时，“,”后跟空格：
int i, j;
在for循环中，“;”后跟空格：
for (int i = 0; i < count; ++i)
在有多个入口参数的函数调用中，“,”后跟一个空格：
addContentView(view, params);

h)变量类型的使用
编程的过程中尽量使用接口编程，而少用类编程。
如：

    List<String> names = new ArrayList<String>();

命名规范

通用规则

命名规范使程序更易读，从而更易于理解。它们也可以提供一些有关标识符功能的信息，以助于理解代码，例如，不论它是一个常量，包，还是类。

包(Packages) 一个唯一包名的前缀总是全部小写的ASCII字母并且是一个顶级域名，通常是com，edu，gov，mil，net，org，或1981年ISO 3166标准所指定的标识国家的英文双字符代码。包名的后续部分根据不同机构各自内部的命名规范而不尽相同。这类命名规范可能以特定目录名的组成来区分部门(department)，项目(project)，机器(machine)，或注册名(login names)。
如：

package com.itotem.view
package com.itotem.utils.xxxx

类(Classes) 命名规则：类名是个一名词，采用大小写混合的方式，每个单词的首字母大写。尽量使类名简洁而富于描述。使用完整单词，避免缩写词(除非该缩写词被更广泛使用，像URL，HTML)
如：

public class Button
public class EditText

接口(Interfaces) 命名规则：接口类名以大写“I”开头，大小写规则与类名相似，
如：

public interface IProjGroupService

方法(Methods) 方法名是一个动词，采用大小写混合的方式，第一个单词的首字母小写，其后单词的首字母大写。
如：

public void onCreate(Bundle savedInstanceState)
public void run()

局部变量(Local Variables) 采用大小写混合的方式，第一个单词的首字母小写，其后单词的首字母大写。变量名应简短且富于描述。变量名的选用应该易于记忆，即，能够指出其用途。尽量避免单个字符的变量名，除非是一次性的临时变量。临时变量通常被取名为i，j，k，m和n，它们一般用于整型。c，d，e，它们一般用于字符型，变量名不应以下划线或美元符号开头。
如：

int i = 0;
float imageWidth = 0;

实例变量(Instance Variables) 大小写规则和类名相似，除了前面需要一个m。
如：

    private int mEmployeeId = 0;
    private String mName = "";

若实例变量为public类型的则和局部变量采用相同的命名规则。
如：

    public int width = 0;
    public String contactName = "";

常量(Constants [采用stiatc final 修饰]) 类常量的声明，应该全部大写，单词间用下划线隔开。(类似C语言的宏定义)。
如：

    private static final int MIN_WIDTH = 4; 
    private static final int MAX_WIDTH = 999;

资源id 资源id全部采用小写，单词之间用下划线隔开。

注意：这个小写规范是Android强制执行的，如果出现大写或者特殊字符工程是不能编译的。会报错
如：

    download
    app_name
    call_log_type

备注(Remark)
所有的标识符名称要求取有意义的单词，不能使用myXXXX和button01等风格的名称。

附加说明
1、从命名中可以直观看懂其定义和用途，否则必须增加注释说明；
2、在同一系统内命名必须保持统一；避免出现类似示例中的情况；
示例：项目组id 变量定义：pgid、projectgroupId、idprojectgroup、idProjGroup
3、避免名字过长、命名采用英文缩写，避免使用汉语拼音【推荐】

组织规范

引入包规范
不允许引入类中未使用的包；
引入包时不能直接引入“.*”，必须明确到引入的类名
可以通过快捷键引入包。Ctrl+Shift+O;

注释规范

a)通用注释规则

b)说明
注释要精简并清晰容易理解；
保持注释与代码同步。
代码质量不好但能正常运行，或者还没有实现的代码用 //TODO:任务；
存在错误隐患的代码用 //FIXME:声明；
对于不建议使用（废弃）的类或者方法，必须在他们的注释中增加 @deprecated

c)javadoc注释标签语法定义说明
@author 对类的说明标明开发该类模块的作者
@version 对类的说明标明该类模块的版本
@see 对类、属性、方法的说明参考转向，也就是相关主题
@param 对方法的说明对方法中某参数的说明
@return 对方法的说明对方法返回值的说明
@exception 对方法的说明对方法可能抛出的异常进行说
@deprecated 对类或方法的说明该类或方法不建议使用

d)类的注释
目的：简单概述该类作用

范围：所有java类，可以不包括javabean

书写规范：类的注释必须写在该类的声明语法之前。在注释中要描述该类的描述，创建者，创建日期。

类注释模板：可以通过eclipse配置（Code Templates 中的 Code 的New Java files）

${filecomment}
${package_declaration}

/**
 * Title: ${project_name}<br>
 * Description: <br>
 * Copyright: Copyright (c) ${year}    <br>
 * Create DateTime: ${date} ${time} <br>
* @author perry.li
 */
${typecomment}
${type_declaration}

类注释示例：

package cn.sh.sstic.projectmanagement.projectfeasibleschemaeval;

/**
 * Title: mwbas2008<br>
 * Description: 可行性方案套数数组定义类<br>
 * Create DateTime: Oct 6, 2008 4:41:03 PM <br>
* @author perry.li
 */
public class FormUtil {

e)方法的注释

目的：简要概述该方法的功能，包括其参数、返回值意义的注释
　范围：java类中的各种方法
注：接口的实现方法的注释应写在接口中而不是实现代码中；
对自动生成的get/set方法不需要添加注释；
如果方法允许null作为参数，或者允许返回值为null，必须在JavaDoc中说明，如果没有说明，方法的调用者不允许使用null作为参数，并认为返回值是null 安全的。

书写规范：方法注释必须写在方法定义之前。该注释包括：方法其功能的简单描述，方法的参数、返回值类型、返回值意义简单的描述。

模板：对于已定义好的接口的方法，可以直接输入 /**回车 eclipse可自动生成注释模板

示例：

    /**
     * 演示方法注释
     * @param args
     * @return
     *  返回 null 表示没有找到
     * @throws Exception
     */
    private String[] demoFunction(String args) throws Exception{
        return null;
    }

f)失效代码块的注释
目的：对一块暂时不启用的代码进行注释。
注：这里并不是指垃圾、无用的代码，只是暂时不启用或暂时不明确的代码

书写规范：失效代码块采用块注释方法行注释方法进行标注。
　　　　注：采用注释块在使用eclipse自带的Format方法（快捷键：Ctrl+Shift+F）时需要配置，去掉选中 “Enable block commnet formatting”

示例：

    // if (1==1) {
    //          
    // } else {
    //
    //      }

或者

    /*      if (1 == 1) {
                // 如果1与1相等的时候
                String code1;
            } else {
                // 如果1与1不相等的时候
                String code2;
            }*/

g)分支语句的注释

目的：简单描述该分支条件的意义

书写规范：在分支语句代码的下一行进行注释

示例：

        if (1==1) {
            //如果1与1相等的时候
            code
        } else {
            //如果1与1不相等的时候
            code
        }

h)变量、常量的注释
目的：简单描述该变量、常量的意义。
书写规范：变量、常量注释必须写在变量、常量定义之前或同一行中，简单描述其代表的意义。
注：对自循环所用的变量（i,j,k,）可以不需要注释。
示例：

String commitFlag; //提交标志
i)@Override的使用
所有的重写方法,在方法开始加上 @Override 关键字。

如：

@Override
public void onCreate(Bundle savedInstanceState) {
}

异常处理规范

重新抛出的异常必须保留原来的异常，即throw new NewException(“message”, e); 而不能写成throw new NewException(“message”)，更不能不继续往上层抛出异常。针对重要的可捕获的业务相关异常，需创建异常处理类，在方法中捕获到异常后，反馈到用户界面上，提示用户【推荐】