奔三搬砖人重撸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。养成一个好的编程习惯非常重要,何况这并不难






  • 0
    点赞
  • 0
    收藏
    觉得还不错? 一键收藏
  • 0
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值