Question

在某些代码库中，我看到了可以描述为默认评论的评论。您通常会在项目的每个文件中找到这些注释，我相信，在大多数情况下，它们是在IDE的帮助下自动生成的。元信息有点不同。它实际上是代码的一部分。我想我最好在例子中说明这一点。这是我们的测试科目（取自现实生活并简化）：

public class UserServiceImpl implements IUserService {

    ////////////////////////////////////////////////////////////////////////
    // Constants
    ////////////////////////////////////////////////////////////////////////

    /** Logger for this class */
    @SuppressWarnings("unused")
    private static final Log LOG = LogFactory.getLog(UserServiceImpl.class);

    ////////////////////////////////////////////////////////////////////////
    // Attributes
    ////////////////////////////////////////////////////////////////////////

    /** User DAO */
    private IUserDao userDao;

    ////////////////////////////////////////////////////////////////////////
    // Constructors
    ////////////////////////////////////////////////////////////////////////

    /**
     * Default constructor
     */
    public UserServiceImpl() {
    }

    public UserServiceImpl(final IUserDao userDao) {
        this.userDao = userDao;
    }

    ////////////////////////////////////////////////////////////////////////
    // Getter and Setter methods
    ////////////////////////////////////////////////////////////////////////

    /**
     * @return value of {@link #userDao} field
     *
     */
    public IUserDao getUserDao() {
        return userDao;
    }

    /**
     * Sets {@link #userDao} field
     *
     * @param userDao User DAO
     */
    public void setUserDao(final IUserDao userDao) {
        this.userDao = userDao;
    }

    ////////////////////////////////////////////////////////////////////////
    // Implemented/Overridden methods
    ////////////////////////////////////////////////////////////////////////

    /**
     *
     * @see IUserService#saveUser(User)
     */
    @Override
    public void saveUser(final User user) {
        fillMissingFields(user);
        userDao.saveUser(user);
    }

    /**
     *
     * @see IUserService#getUserById(Integer)
     */
    @Override
    public List<User> getUserById(final Integer id) {
        return userDao.getUserById(id);
    }

    /**
     *
     * @see IUserService#getUserList(IEnvironmentContext)
     */
    @Override
    public List<User> getUserList(final @SuppressWarnings("unused") IEnvironmentContext context) {
        return userDao.getUserList();
    }

    ////////////////////////////////////////////////////////////////////////
    // Helper methods
    ////////////////////////////////////////////////////////////////////////

    private void fillMissingFields(final User user) {
        user.setLastUpdated(new Date());
    }

    ////////////////////////////////////////////////////////////////////////
    // toString() method
    ////////////////////////////////////////////////////////////////////////

    /**
     *
     * @see Object#toString()
     */
    @Override
    public String toString() {
        return "UserServiceImpl {...}";
    }
}

这个类包含了我想讨论的很多概念，所以我将它们分成以下几种：

1）部分默认注释 - 对于每个类的部分，有一个3行注释（如常量，构造函数，...）。请注意，我不是在讨论课程的逻辑部分（例如// user managenet或// Account Balance calculation）。

2）Getter和Setter默认注释 - 对set / get方法的注释，它只是告诉相应的方法集返回字段值。

3）元评论 - 描述某些java语言结构含义的注释。上面的示例：@see IUserService#saveUser(User) - 告诉该方法被覆盖/实现，父方法的位置Default constructor - 告诉它是Java类的默认构造函数Logger for this class。

4）@SuppressWarnings（“unused”） - 在我的具体例子中，它曾经说过，LOG未在课程中使用（LOG实际上从未在类中使用，但IDE不会显示警告）并且没有使用context参数，但它没关系（假设context是一些一般信息，如果实现不使用它通常是完全正常的）

5）接口的I前缀 - 前缀告诉，这是接口。

6）final方法参数 - 防止方法体中的代码更改其值

我想了解您对课堂中默认评论和元信息的看法。为了使其更直接，我建议您为每种类型投票，评分从+5到 - 5：

+5 - 我认为必须并且应该由每个Java开发人员完成，甚至应该使用工具（例如checkstyle）强制执行 ...... 0 - 我不在乎。如果有人会告诉我这样做，我会 - 这些评论不会带来任何正面或负面价值。
...... -5 - 我强烈反对每个人都这样做。一旦看到这样的默认评论/元信息，就应该从课堂上删除。

我也坚信，总是向你解释选项并回答问题是非常重要的：你为什么这么认为？（我个人总是试着遵循这条规则）。因此，我也鼓励您解释您为特定类型提供的要点。

我会在大约一周内接受大多数SO赞成回答。

PS。：你们中的一些人可能认为答案是不言而喻的，但请相信我，我们每个人都是非常不同的，对你们来说不言自明的事情可能会给我带来惊喜反之亦然。所以我鼓励你参加这个讨论。（我会很感激）

Answer 1

代码文档的目的是帮助阅读代码的任何人理解它。这仅此而已。这是你应该着眼于的目标，并确保你永远不会失去它。文档的价值可以表示为(<the time it would take me to read the code without the documentation> - <the time it takes me to read the code with the documentation>) * <my salary>)从中减去您编写文档所花费的时间乘以您的工资并获得净值。如果这个数字可能是负数，请不要费心去写。这些公式显然纯粹是理论上的，但它们允许我们构建一些问题。

示例代码中的注释是否帮助我理解了代码？没有一点。对于那些在Java方面有一定经验的人来说，其中的信息应该是非常明显的。

他们阻碍了我吗？是的，因为我滚动它的时间比没有评论时要长三倍。

如果要更改代码，保持评论一致会有多难？我相信，这就是关键。过于复杂的评论惯例更有可能被打破，这是可能发生的最坏情况：评论不仅是多余的，而且是误导性的。这就像是从维护开发中偷走时间。

总而言之，文档的文档是错误的。当你权衡你的文档选择时，你应该始终牢记读者：这篇文档如何使他们受益？如果你牢记这一点，你将做出正确的选择。

Java类/接口中的缺省注释和元信息

2 个答案: