【发布时间】：2011-06-17 21:59:45
【问题描述】：
在一些代码库中，我看到了可以描述为 默认 cmets 的 cmets。这些 cmets 您通常会在项目的每个文件中找到，我相信在大多数情况下，它们是在 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) 部分默认 cmets - 对于类的每个部分，都有一个 3 行注释（如常量、构造函数等）。请注意，我不是在谈论课程的逻辑部分（例如 // user managenet 或 // Account Balance calculation）。
2) Getter 和 Setter 默认 cmets - 用于 set/get 方法的 cmets，只告诉对应的方法集返回字段值。
3) Meta cmets - 描述一些 java 语言结构含义的 cmets。上面的例子：@see IUserService#saveUser(User) - 告诉方法被覆盖/实现和父方法的位置，Default constructor - 告诉它是 Java 类的默认构造函数，Logger for this class。
4) @SuppressWarnings("unused") - 在我的具体示例中，它曾经说过，LOG 没有在课堂上使用（LOG 实际上从未在课堂上使用过，但IDE不会显示警告）和context参数没有使用，但没关系（假设context是一些通用信息，如果实现不使用它通常是完全正常的）。
5) I 接口前缀 - 前缀表示这是接口。
6) final 用于方法参数 - 防止方法体中的代码更改其值
我想知道您对课程中默认 cmets 和元信息的看法。 为了更直接，我建议您投票支持从 +5 到 - 等级的每种类型5：
+5 - 我认为这是必须，每个 Java 开发人员都应该这样做，甚至应该使用工具（如 checkstyle）来强制执行
...
0 - 我不在乎。如果有人告诉我这样做，我会 - 这些 cmets 不会带来任何正面或负面的价值。
...
-5 - 我强烈建议大家不要这样做。此类默认 cmets/元信息应在您看到后立即从课程中删除。
我也坚信，始终向您解释选项并回答问题非常重要：您为什么这么认为？ （我个人总是尽量遵守这条规则）。所以我也鼓励你解释你对特定类型给出的观点。
我将在大约一周内接受大多数支持投票的答案。
PS.：你们中的一些人可能认为答案是不言而喻的，但相信我，我们每个人都非常不同，对你来说不言而喻的事情可能会让我和反之亦然。所以我鼓励你无论如何都要参与这个讨论。 （我会很感激的）
【问题讨论】：
-
虽然这可能是一个有趣的讨论话题，但这似乎并不是一个具体的问题。
标签： java coding-style comments