奔三搬砖人重撸Java之注释与doc

之前一直不重视注释和文档，结果最近重构前人留下的代码才深感注释的重要性，花在理解代码逻辑上的时间远远多于撸代码的，因为项目很多人经手过，各人水平又不相同，又没有统一的编码规范导致整个项目混乱不已，后面的人难以继续开发，最近阿里发布了自己的Java编程规范，很不幸的发现这个项目简直就是反面教材集，因此决定好好学习下Java注释和javadoc的应用。

1.注释：

Java两种注释风格：“//”注释一行；以/*开始和*/结束，可以跨越多行；

阿里的注释规约：

1.类、类属性、类方法的注释必须使用Javadoc规范，使用/**内容*/格式，不得使用//xxx方式。

2.所有的抽象方法（包括接口中的方法）必须要用Javadoc注释、除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。

3.所有的类都必须添加创建者信息。
4.方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释使用/* */注释，注意与代码对齐。
5.所有的枚举类型字段必须要有注释，说明每个数据项的用途。

6.与其“半吊子”英文来注释，不如用中文注释把问题说清楚。专有名词与关键字保持英文原文即可。

例子：

package com.ws.junit.test;

import java.lang.reflect.Array;
import java.util.Arrays;

/**
 * 用来练习junit的类
 * @author ws
 *
 */
public class FirstDayAtSchool {

	/**
	 * returns the things in the bag
	 * @author ws
	 * @return String[]
	 */
	public String[] prepareMyBag() {
		String[] schoolBag = { "Books", "Notebooks", "Pens"};
		System.out.println("my bag contains: " + Arrays.toString(schoolBag));
		return schoolBag;
	}
	
	/**
	 * 将pencils添加进bag中
	 * @return return String[]
	 */
	public String[] addPencils() {
		String[] schoolBag = { "Books", "Notebooks", "Pens","Pencils"};
		System.out.println("my bag contains: " + Arrays.toString(schoolBag));
		return schoolBag;
	}
}

2.Javadoc文档使用

如何生存javadoc文档呢，在ecplise中点击project->Generate javadoc,选择jdk/bin目录下的javadoc.exe和需要生存文档的包及输出位置，就行了。

如果出现中文乱码那就先将项目设置成UTF-8的格式然后在生成javadoc最后一步输入：javadoc -encoding UTF-8 -charset UTF-8。选择完成后你可以发现在project里面出现了一个目录doc里面就是你的javadoc,想写出好的javadoc一个非常好的办法就是多参考java的api doc。养成一个好的编程习惯非常重要，何况这并不难