В некоторых кодовых файлах я видел комментарии, которые можно охарактеризовать как комментарии по умолчанию. Эти комментарии вы обычно найдете в каждом файле проекта, и, я считаю, в большинстве случаев они автоматически генерируются с помощью IDE. Мета-информация немного отличается. Это часть кода. Думаю, мне лучше показать это на примере. Это наш испытуемый (взяты из реальной жизни и упрощенный):Замечания по умолчанию и метаинформация в Java-классах/интерфейсах
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) Раздел по умолчанию комментарии - для каждого раздела класса есть один комментарий из трех строк (например, константы, конструкторы, ...). Обратите внимание, что я не говорю о логических разделах класса (например, // user managenet или // Account Balance calculation).
2) Комментарии по умолчанию Getter and Setter - комментарии для методов set/get, которые просто указывают, что соответствующие методы задают значение поля возврата.
3) Мета комментарии - комментарии, которые описывают смысл некоторых конструкций языка java. Примеры сверху: @see IUserService#saveUser(User) - указывает, что метод переопределен/реализован и расположение родительского метода, Default constructor - указывает, что он по умолчанию является конструктором класса Java, Logger for this class.
4) @SuppressWarnings («неиспользованные») - в моем конкретном примере он имел обыкновение говорить, что LOG не используется в классе (LOG не действительно никогда не используется в классе, но IDE не будет отображаться предупреждение) и context аргумент не используется, но все в порядке (при условии, что context - это общая информация, и обычно это нормально, если реализации не используют его).
5) I префикс для интерфейсов - префикс сообщает, что это интерфейс.
6) final для аргументов методы - предотвращает код в теле метода, чтобы изменить это значение
Я хотел бы знать Ваше мнение о комментариях по умолчанию и мета-информации в классах. Для того, чтобы сделать его более простым, я предлагаю вам проголосовать за каждый тип с оценками от +5 до -5:
+5 - Я думаю, что это обязательно, и это должно быть сделано каждым разработчик Java и должны даже применяться с инструментами (например, checkstyle)
...
- Мне все равно. Если кто-то скажет мне сделать это, я буду - эти комментарии не принесут никакого положительного или отрицательного значения.
...
-5 - Я категорически отвергаю всех, чтобы это сделать. Такие комментарии/метаданные по умолчанию должны быть удалены из класса, как только вы его увидите.
Я также твердо верю, что очень важно всегда объяснять вам вариант и отвечать на вопрос: почему вы так думаете? (Я лично стараюсь всегда следовать этому правилу). Поэтому я также призываю вас объяснить, какие моменты вы указали для определенного типа.
Я принимаю ответ с большинством голосов SO за одну неделю.
PS: Некоторые из вас могут подумать, что ответ очевиден, но поверьте мне, каждый из нас очень по-другому, и то, что самоочевидно для вас, может быть неожиданным для меня и наоборот. Поэтому я призываю вас участвовать в этом обсуждении в любом случае. (Буду признателен за это)
Хотя, возможно, интересная тема для обсуждения, это не похоже на конкретный вопрос. –