实践中的重构23_详尽的注释未必是好注释

注释一直是软件开发中的一个老大难问题。
代码中一个注释都没有是一种常见情况，给后来的开发维护带来巨大的成本。
代码中注释零零散散也是一种常见情况，这个依赖于程序员，有的程序员自觉的写上注释，有的觉得无所谓，干脆不写，有的在该写的地方写，不该写的地方省略，有的在不该写的地方写，该写的地方留白让后人抓狂。
系统大了，代码多了，公司一般都会出台一些强制性的代码规范，规范中自然少不了注释规范。于是，程序员为了满足代码注释规范，辛辛苦苦的添加了满屏的注释。
而实际上这种出发点是为了满足规范的注释是少有人看，也少有被看的价值。大家的关注点是在有没有注释上，而不是在注释的质量上。因为该注释被加上去的原因是规范需要，而不是代码或者程序员需要。这样的注释自然就少有人去精心维护。越是少有人去维护，注释和代码就越脱节，于是注释的价值随着时间的推移就更小了，一个恶性循环就这样华丽的诞生了。
有的注释为了满足规范写的很详尽，以为这样的注释就是好的注释。殊不知注释和代码一样，也是有质量的，也一样有可能散发一些不好的味道。
且看下面一个类的方法注释。

/**
 * 上传文件帮助类。
 * */
public class FillUploadHelper {

	/**
	 * 得到一个用户上传文件的文件路径。
	 * 
	 * <pre>
	 * 用户上传文件的文件路径为：
	 * 最高一级目录\年月\年月日\用户userId的8-10位\5-7位\2-4位\文件名。
	 * 例如一个用户的id为0123456789,文件上传的日期为20110103，文件名为"allen.txt"，则上传文件的文件路径为：
	 * 最高一级目录\201101\20110103\789\456\123\allen.txt。
	 * </pre>
	 * 
	 * @param userId
	 *            用户id,10位。
	 * @param date
	 *            上传文件的时间　yyyymmdd格式。
	 * @param fileName
	 *            文件名。
	 * 
	 * */
	public String getFilePath(String userId, String date, String fileName) {
		return null;
	}

	/**
	 * 得到一个用户上传文件的目录。
	 * 
	 * <pre>
	 * 用户上传文件的目录为：
	 * 最高一级目录\年月\年月日\用户userId的8-10位\5-7位\2-4位。
	 * 例如一个用户的id为0123456789，文件上传的日期为20110103，则上传文件的目录为：
	 * 最高一级目录\201101\20110103\789\456\123。
	 * </pre>
	 * 
	 * @param userId
	 *            用户id,10位。
	 * @param date
	 *            上传文件的时间　yyyymmdd格式。
	 * 
	 * */
	public String getFileDir(String userId, String date) {
		return null;
	}

	/**
	 * 得到一个用户上传文件的用户目录。
	 * 
	 * <pre>
	 * 该用户目录为：
	 * \用户userId的8-10位\5-7位\2-4位。
	 * 如userId为0123456789，则用户目录为：
	 * \789\456\123。
	 * </pre>
	 * 
	 * @param userId
	 *            用户id,10位。
	 * @return 用户目录。
	 * */
	private String getUserDir(String userId) {
		return null;
	}

	/**
	 * 得到一个用户上传文件的日期目录。
	 * 
	 * <pre>
	 * 该日期目录为：
	 * \年月\年月日。
	 * 如日期为20110103， 则日期目录为：
	 * \201101\20110103。
	 * </pre>
	 * 
	 * @param date
	 *            上传文件的时间 yyyymmdd格式。
	 * */
	private String getDateDir(String date) {
		return null;
	}

	/**
	 * 得到用户上传文件的最高一级目录。
	 * 
	 * @return 用户上传文件的最高一级目录。
	 * */
	private String getUploadDir() {
		return null;
	}
}

可以说这个注释已经很详尽了，每个方法都详尽的注释了上传文件的路径名的相关信息。
但是同代码一样，这段注释是有些不好的味道的。
方法注释中有重复的片段，而重复的注释意味着如果上传文件的目录规则改变的话，一大堆方法的注释都要改动。重复总是不好的。
OOP的最小构建单位是类，而不是方法。这句话不仅适用于领域对象，一样适用于工具类。通过抽取方法级别的详尽注释到类上，集中上传文件的目录规则，从而减少重复。

/**
 * 上传文件帮助类。
 * 
 * <pre>
 * 
 * 用户上传文件的文件路径分为4部分。
 * 
 * 系统配置的最高一级目录。uploadDir。
 * 用户上传文件的日期目录dateDir，格式为\年月\年月日。
 * 用户上传文件的用户目录userDir，格式为\用户userId的8-10位\5-7位\2-4位。
 * 用户上传文件的文件名。fileName。
 * 
 * 例如系统配置的目录为\saveUpload,一个用户的id为0123456789,
 * 文件上传的日期为20110103,文件名为"allen.txt",则上传文件的文件路径为：
 * 
 * \saveUpload\201101\20110103\789\456\123\allen.txt
 * 
 * <pre>
 * */
public class FillUploadHelper2 {

	/**
	 * 得到一个用户上传文件的文件路径。
	 * 
	 * @param userId
	 *            用户id,10位。
	 * @param date
	 *            上传文件的时间　yyyymmdd格式
	 * @param fileName
	 *            文件名
	 * 
	 * */
	public String getFilePath(String userId, String date, String fileName) {
		return null;
	}

	/**
	 * get uploadDir+dateDir+userDir。
	 * 
	 * @param userId
	 *            用户id,10位。
	 * @param date
	 *            上传文件的时间　yyyymmdd格式
	 * 
	 * */
	public String getFileDir(String userId, String date) {
		return null;
	}

	/**
	 * get userDir。
	 * 
	 * @param userId
	 *            用户id,10位。
	 * @return 用户目录。
	 * */
	private String getUserDir(String userId) {
		return null;
	}

	/**
	 * get dateDir。
	 * 
	 * @param date
	 *            上传文件的时间 yyyymmdd格式。
	 * */
	private String getDateDir(String date) {
		return null;
	}

	/**
	 * get uploadDir。
	 * 
	 * @return 用户上传文件的最高一级目录。
	 * */
	private String getUploadDir() {
		return null;
	}

}