Java项目开发规范

为何制定开发规范

定义规范的目的是增加程序和文档可读性,减少出现错误的几率。

  1. 减少维护成本;一个软件的生命周期中,80%的花费在于维护,另一方面,几乎没有任何一个软件,在其整个生命周期中,均由最初的开发人员来维护,规范的编码减少人员变动带来的维护成本。
  2. 改善软件的可读性;可以让程序员尽快而彻底地理解新的代码。

开发中需要避免的问题

  1. 在循环中对字符串操作时用String;
  2. 滥用synchronized 关键字;
  3. 对文件或者数据库的操作不及时关闭;
  4. 一个方法的代码过长,超过1000行;
  5. 不写注释,或者注释不清晰;命名不规范;排版格式混乱,不注意缩进与对齐等;
  6. 滥用public公共类定义;
  7. 在程序中使用硬编码;
  8. 在程序代码中存在垃圾数据文件(例如.bak,.svn文件夹等);
  9. 所有调试信息直接System.out.print打印到控制台;
  10. 对数组为空、数组越界、页面传递的参数为空等异常情况不做任何处理;
  11. 方法的参数很多,不要超过5个;

命名规范

  1. 包(Packages):全部用小写字母。

    例如:com.meic.tools;

  2. 类(Classes):首字母大写,多个单词则每个单词的第一个字母大写,其余小写。努力让你的类名简单和有描述性。可以使用缩写。

    例如:public class DBService{}

  3. 接口(Interfaces):接口名第一个字母必须是“I”,其余部分同类名,第二个字母必须大写。

    例如:interface ISchedule{}

  4. 方法(Methods):方法名必须是英文动词。除第一个字母小写外,内部每一个单词的第一个字母必须大写。

    例如:void run(){}

  5. 变量(Variables)和参数(Parameter):全部用小写,可以用缩写。变量名应该短而有意义。变量名必须是能帮助记忆的,也就是说,即使是一个随便看看代码的人也能明白变量的用意。单个字符的变量应该避免。临时变量除外。临时整数变量常用名是i,j,k,m,和n;临时字符变量用c,d,和e。

    例如:int i; char c;

  6. 常量(Constants):所有的常量必须都是大写,单词之间用‘_’分割。

    例如:static final int MAX_WIDTH = 999;

注释规范

1. 导入代码注释模板

  • 下载代码注释模板文件codetemplates.xml(内容见下面③);
  • 打开本机的Eclipse,按照这样的步骤Window->Preference->Java->Code Style->Code Template打开代码模板设置面板;
  • 选择import,导入codetemplates.xml;
  • 勾选中Automatically add comments for new methods and types,选择OK就完成导入了。

2. 应用注释模板

  • 完成以上操作后,我们新建一个类文件时,默认会自动生成该类的说明;
  • 如果要对一个类(属性,方法)手动生成注释,在定义完成后,选中该类(属性,方法),使用ALT+SHIFT+J快捷键,即可按模板生成注释;
  • 模板中有TODO提示内容的,是需要自己手动去修改的,比如类的描述,方法的描述等

下面是利用模板生成注释的例子:

/**
 * @description: TODO(描述这个类的作用)
 * @author HP
 * @date 2014-08-22
 */

public class CommentTest {

    /**
    * @fields id : TODO(描述这个变量的作用)
    */
    private int id;
    /**
    * @description: TODO(描述这个方法的作用)
    * @author: HP
    * @param param1
    * @param param2
    * @return
    */
    public int doOperate(int param1,int param2){
        return 0;
    }

    /**
    * @description: 这个方法用来处理一个简单的流程
    * @author: HP
    * @param param1
    * @param param2
    * @return
    */
    public int doOperate2(int param1,int param2){
        return -1;
    }

3. 模板codetemplates.xml内容

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<templates>
    <template autoinsert="false" context="methodcomment_context"
        deleted="false" description="Comment for non-overriding methods"
        enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.methodcomment"
        name="methodcomment">
        /**
         * @description: ${todo}(描述这个方法的作用)
         * @author: ${user}
         * ${tags}
         */
    </template>
    <template autoinsert="false" context="filecomment_context"
        deleted="false" description="Comment for created Java files" enabled="true"
        id="org.eclipse.jdt.ui.text.codetemplates.filecomment" name="filecomment" />
    <template autoinsert="false" context="fieldcomment_context"
        deleted="false" description="Comment for fields" enabled="true"
        id="org.eclipse.jdt.ui.text.codetemplates.fieldcomment" name="fieldcomment">
        /**
         * @fields ${field} : ${todo}(描述这个变量的作用)
         */
    </template>
    <template autoinsert="false" context="typecomment_context"
        deleted="false" description="Comment for created types" enabled="true"
        id="org.eclipse.jdt.ui.text.codetemplates.typecomment" name="typecomment">
        /**
         * @description: ${todo}(描述这个类的作用)
         * @author ${user}
         * @date ${date}
         */
    </template>
</templates>

发表评论