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