Don't comment bad code - rewrite it.
Brian W. Kernighan and P. J. Plaugher
Эта цитата из начала главы 4: Comments из книги Clean Code (Robert C.Martin)
Я согласен с большинством положений этой главы.
Основной посыл — комментарии в коде следует писать только в случае крайней необходимости. Если вам приходится комментировать код, это стоит рассматривать как провал, так как в большинстве случаев причина появления комментариев — плохой, нечитаемый код.
Более того комментарии быстро начинают расходится с кодом, который они описывают и могут вводить в заблуждение.
Значит ли это, что комментарии в коде писать не надо вообще?
Нет. Комментарии в некоторый случаях полезны:
1) Хорошее описание public API. Если вы разрабатываете библиотеку, которая используется другими командами внутри вашей компании или вне ее. Или API/Endpoint, которое вызывают другие команды. Если это Java - можно писать Javadocs. Но описание API должно быть хорошим и полезным. Писать комментарии в стиле капитан очевидность смысле не имеет. Часто приходилось видеть Javadocs:
/**
* Processes user order.
*
* @param userId the user id
* @param products the products
* @param applyDiscount the apply discount
* @param sendEmail the send email
*/
public void processUserOrder(long userId, List<Product> products,
boolean applyDiscount, boolean sendEmail) {
// ...
}
```
В таком Javadocs смысла не очень много.
2) Описание причин, почему так сделано. Если код выглядит плохо и очень хочется его переписать, но вы уже пытались и по каким-то причинам были вынуждены остановиться на воркэраунде, имеет смысл в комментарии объяснить, почему сделано именно так, а не иначе.
3) Предостережения. Похоже на предыдущий вариант, но если вы знаете, что изменения в этом коде в ту или иную сторону или его использование в определенном контексте приведет к очень плохим последствиям - стоит написать комментарий.
4) Пояснения, которые сложно выразить в коде. Иногда код невозможно сделать более читаемым из-за особенностей языка программирования, и он всё равно остаётся не очень удобным для восприятия. В таких случаях можно оставить информационный комментарий.
5) TODO. Имеет смысл оставлять такие комментарии о том, что планируете изменить, дописать, улучшить в будущем.
6) Копирайты, если это требует ваша компания. Иногда компании по дефолту заставляют в каждый файл добавлять комментарий вверху или внизу с копирайтом, лицензией и т.д.
В большинстве других случаев комментарии бесполезны или даже вредны: они перегружают мозг бессмысленной информацией при чтении кода, могут вводить в заблуждение и требуют дополнительных усилий разработчика для поддержки в актуальном состоянии.
Например:
1) Комментарии в стиле капитан очевидность.
//Increment i
i++;
/** The name */
private String name;
2) Комментарии, которые можно убрать переименовав функцию, переменную или аргумент.
// timeout in milliseconds
long TIMEOUT = 5000;
Лучше:
long TIMEOUT_IN_MILLISECONDS = 5000;
//Extract user name from the input string
public String parse(String str) {
...
Лучше:
public String extractUserName(String commandLineParameters) {
...3) Комментарии, когда можно вынесли логику в отдельную функцию.
// Проверяем, можно ли показать пользователю промо-баннер
if (user != null
&& user.isLoggedIn()
&& !user.isPremium()
&& featureFlags.isPromoBannerEnabled()) {
showPromoBanner(user);
}
Лучше:
if (shouldShowPromoBanner(user)) {
showPromoBanner(user);
}
private boolean shouldShowPromoBanner(User user) {
return user != null
&& user.isLoggedIn()
&& !user.isPremium()
&& featureFlags.isPromoBannerEnabled();
}4) Закомментированный старый код. Просто удаляйте код. Сейчас уже давно существует система контроля версий, которая хранит всю историю.
5) Комментарии (Javadocs) для не публичного API. Писать Javadocs ради самого факта их наличия не нужно. Не стоит писать комментарии для API, которое никем, кроме вас и вашей команды, не используется.