实践中的重构26_奇怪的接口注释

最近又看到奇怪的注释。

	/**
	 * 用户查询服务。
	 * 
	 * <pre>
	 * 提供接口
	 * 1 VIP用户查询服务。
	 * 2 使用用户名查询用户服务。
	 * 3 使用id查询用户服务。
	 * </pre>
	 * */
	public interface UserQuery {

		/**
		 * 用户是否是VIP用户？
		 * 
		 * <pre>
		 * 当UserDO中vip为true时返回true。
		 * </pre>
		 * */
		public boolean isVIPUser(String id);

		public User findUserByName(String name);

		public User findUserById(String id);
	}

该处注释有两个问题。
接口作为一个顶级类型，是否需要把该接口中所有的方法1234的列出来呢。不必的吧。首先，接口作为一组操作集合的抽象，其中包含的方法也是可变的，这样一来，改动方法还得改注释保持同步。其次，当代IDE对于找引用，显示方法列表之类的任务的支持已经很强大了，没有必要浪费人力手工维护一份冗余的信息。再其次，接口的抽象级别是高于方法的，把方法的主要功能列举在接口注释中，有混淆抽象级别的嫌疑。
方法的注释中，写明了该接口方法的实现细节。这个注释风格是完全错误的。接口方法作为一个抽象，本意就是把操作的服务契约和实现的细节分离开来。作为接口的使用方，只需要关心接口的服务契约即可，使用方不必也不用关心底层的具体实现。作为接口的实现方，则有自由采用任何方式实现，只要遵守服务契约即可。那么这个方法的实现注释就是完全没有意义的。