代码规范、GitHub提交源码的标准 答题人-杨宇杰

1.格式与命名规范
1.1 缩进
使用Tab缩进，而不是空格键
1.2 换行
每行120字符
if,for,while语句只有单句时，如果该句可能引起阅读混淆，需要用" {"和"}"括起来，否则可以省略。

//错误，需要使用花括号{}括起来
if (condition)
    if(condition) doSomething();
else
    doSomething();

1.3 命名规则
不允许使用汉语拼音命名
遇到缩写如XML时，仅首字母大写，即loadXmlDocument()而不是loadXMLDocument()
Package名必须全部小写，尽量使用单个单词
Interface名可以是一个名词或形容词(加上'able','ible', or 'er'后缀)，如Runnable，Accessible。
为了基于接口编程，不采用首字母为I或加上IF后缀的命名方式，如IBookDao,BookDaoIF。
页面部件名建议命名为：btnOK、lblName或okBtn、nameLbl。(II)
其中btn、lbl缩写代表按钮(Button)、标签(Label)。
局部变量及输入参数不要与类成员变量同名(get/set方法与构造函数除外)
1.4 声明
修饰符应该按照如下顺序排列：public, protected, private, abstract, static, final, transient, volatile, synchronized, native, strictfp。
类与接口的声明顺序(可用Eclipse的source->sort members功能自动排列):
静态成员变量 / Static Fields
静态初始化块 / Static Initializers
成员变量 / Fields
初始化块 / Initializers
构造器 / Constructors
静态成员方法 / Static Methods
成员方法 / Methods
重载自Object的方法如toString(), hashCode() 和main方法
类型(内部类) / Types(Inner Classes)
同等的类型，按public, protected, private的顺序排列。
2.注释规范
2.1 注释类型
2.1.1 JavaDoc注释
2.1.2 失效代码注释
由/*...*/界定，标准的C-Style的注释。专用于注释已失效的代码。

/*
 * Comment out the code
 * String s = "hello";
 * System.out.println(s);
 */

2.1.3 代码细节注释
由//界定，专用于注释代码细节，即使有多行注释也仍然使用//，以便与用/**/注释的失效代码分开
除了私有变量外，不推荐使用行末注释。

class MyClass {

    private int myField; // An end-line comment.

    public void myMethod {

       //a very very long
       //comment.
       if (condition1) {
          //condition1 comment
          ...
        } else {
          //elses condition comment
          ...
        }
    }
}

2.2 注释的格式
注释中的第一个句子要以（英文）句号、问号或者感叹号结束。Javadoc生成工具会将注释中的第一个句子放在方法汇总表和索引中。
为了在JavaDoc和IDE中能快速链接跳转到相关联的类与方法，尽量多的使用@see xxx.MyClass，@see xx.MyClass#find(String)。
Class必须以@author 作者名声明作者，不需要声明@version与@date，由版本管理系统保留此信息。
2.3 注释的内容
2.3.1 可精简的注释内容
注释中的每一个单词都要有其不可缺少的意义，注释里不写"@param name -名字"这样的废话。
如果该注释是废话，连同标签删掉它，而不是自动生成一堆空的标签，如空的@param name，空的@return。
2.3.2 推荐的注释内容
对于API函数如果存在契约，必须写明它的前置条件(precondition)，后置条件(postcondition)，及不变式(invariant)。
对于调用复杂的API尽量提供代码示例。
对于已知的Bug需要声明。
在本函数中抛出的unchecked exception尽量用@throws说明。
2.3.3 Null规约
如果方法允许Null作为参数，或者允许返回值为Null，必须在JavaDoc中说明。
如果没有说明，方法的调用者不允许使用Null作为参数，并认为返回值是Null Safe的。

/**
 * 获取对象.
 *
 * @ return the object to found or null if not found.
 */
Object get(Integer id){
    ...
}

2.3.4 特殊代码注释
代码质量不好但能正常运行，或者还没有实现的代码用//TODO: 或 //XXX:声明
存在错误隐患的代码用//FIXME:声明
3.编程规范
3.1基本规范
当面对不可知的调用者时，方法需要对输入参数进行校验，如不符合抛出IllegalArgumentException，建议使用Spring的Assert系列函数。
隐藏工具类的构造器，确保只有static方法和变量的类不能被构造实例。
变量，参数和返回值定义尽量基于接口而不是具体实现类，如Map map = new HashMap();
代码中不能使用System.out.println()，e.printStackTrace()，必须使用logger打印信息。
3.2 异常处理
重新抛出的异常必须保留原来的异常，即throw new NewException("message", e); 而不能写成throw new NewException("message")。
在所有异常被捕获且没有重新抛出的地方必须写日志。
如果属于正常异常的空异常处理块必须注释说明原因，否则不允许空的catch块。
框架尽量捕获低级异常，并封装成高级异常重新抛出，隐藏低级异常的细节。(III)
3.3 代码度量
3.3.1 耦合度度量
DAC度量值不要不大于7 
解释：DAC(Data Abstraction Coupling)数据抽象耦合度是描述对象之间的耦合度的一种代码度量。DAC度量值表示一个类中有实例化的其它类的个数。
CFO度量值不要不大于20 
解释：CFO(Class Fan Out)类扇出是描述类之间的耦合度的一种代码度量。CFO度量值表示一个类依赖的其他类的个数。
3.3.2 方法度量
方法（构造器）参数在5个以内 
太多的方法（构造器）参数影响代码可读性。考虑用值对象代替这些参数或重新设计。
方法长度150行以内 
CC 度量值不大于10
解释：CC(CyclomaticComplexity)圈复杂度指一个方法的独立路径的数量，可以用一个方法内if,while,do,for,catch,switch,case,?:语句与&&,||操作符的总个数来度量。
NPath度量值不大于200
解释：NPath度量值表示一个方法内可能的执行路径的条数。
3.3.3 其他度量
布尔表达式中的布尔运算符(&&,||)的个数不超过3个
if语句的嵌套层数3层以内
文件长度2000行以内
匿名内部类20行以内 
太长的匿名内部类影响代码可读性，建议重构为命名的（普通）内部类。
3.4 JDK5.0
重载方法必须使用@Override，可避免父类方法改变时导致重载函数失效。
不需要关心的warning信息用@SuppressWarnings("unused"), @SuppressWarnings("unchecked"), @SuppressWarnings("serial") 注释

 

 

GitHub提交源码标准：

1.Clone自己的项目
我们以我在 GitHub 上创建的 test 项目为例，执行如下命令：
git clone git@github.com:stormzhang/test.git
这样就把 test 项目 clone 到了本地，你可以把 clone 命令理解为高级点的复制，这个时候该项目本身就已经是一个git 仓库了，不需要执行 git init 进行初始化，而且甚至都已经关联好了远程仓库，我们只需要在这个 test 目录下任意修改或者添加文件，然后进行 commit ，之后就可以执行：

git add ......

git commit ......
(add和commit方法请参考后面的git使用方法)
git push origin master
进行代码提交，这种是最简单方便的一种方式。

2.关联本地已有项目
如果我们本地已经有一个完整的 git 仓库，并且已经进行了很多次 commit ，这个时候第一种方法就不适合了。

假设我们本地有个 test2 的项目，我们需要的是在 GitHub 上建一个 test 的项目，然后把本地 test2 上的所有代码 commit 记录提交到 GitHub 上的 test 项目。

第一步就是在 GitHub 上建一个 test 项目，这个想必大家都会了，就不用多讲了。

第二步把本地 test2 项目与 GitHub 上的 test 项目进行关联，切换到 test2 目录，执行如下命令：

git remote add origin git@github.com:stormzhang/test.git
什么意思呢？就是添加一个远程仓库，他的地址是 git@github.com:stormzhang/test.git ，而 origin 是给这个项目的远程仓库起的名字，是的，名字你可以随便取，只不过大家公认的只有一个远程仓库时名字就是 origin ，为什么要给远程仓库取名字？因为我们可能一个项目有多个远程仓库？比如 GitHub 一个，比如公司一个，这样的话提交到不同的远程仓库就需要指定不同的仓库名字了。

查看我们当前项目有哪些远程仓库可以执行如下命令：

git remote -v
接下来，我们本地的仓库就可以向远程仓库进行代码提交了：

git push origin master
就是默认向 GitHub 上的 test 目录提交了代码，而这个代码是在 master 分支。当然你可以提交到指定的分支，这个之后的文章再详细讲解。

对了，友情提醒，在提交代码之前先要设置下自己的用户名与邮箱，这些信息会出现在所有的 commit 记录里，执行以下代码就可以设置：

git config —global user.name "stormzhang"
git config —global user.email "stormzhang.dev@gmail.com"