之前一直不重视注释和文档,结果最近重构前人留下的代码才深感注释的重要性,花在理解代码逻辑上的时间远远多于撸代码的,因为项目很多人经手过,各人水平又不相同,又没有统一的编码规范导致整个项目混乱不已,后面的人难以继续开发,最近阿里发布了自己的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。养成一个好的编程习惯非常重要,何况这并不难