Комментарии в коде?

Question

[Arbil]

Всем привет

Я читал книгу "Чистый код" авторства Роберта Мартина
И в этой книге книге сказано что если коду нужны комментарии, значит это не совсем хороший код(Конечно это не дословная цитата, я просто попытался донести мысль)

И в данный момент читаю книгу "Совершенный код" авторства Стива Макконнелла
И в этой книге автор утверждает что оформление комментариев так же важно как и названия переменных, функций, классов и т.д.

Так как я начинающий программист самоучка и у меня очень мало опыта, я не знаю кому верить. Правда ли что если к коду нужны комментарии, то он не совсем качественный или же к коду нужно оформлять комментарии

Answer 1

[Иван Шумов]

Давайте перестанем путать комментарии в коде и документацию. Если первое предназначено для объяснения как это вообще работает, то второе ставит перед собой цель описания интерфейса взаимодействия, краткие описания с примерами использования и другие вещи, позволяющие, например, автоматически генерировать документацию

Answer 2

[xmoonlight]

Комментарии в коде необходимы только в случаях:
1. Класс - в самом начале: его краткое описание и назначение.
2. Метод - если названия и переменных метода недостаточно для понимания его функционирования.
3. Места, где трудночитаемый код: этажерки условий, запросов к БД, и подобные.

Структура кода и названия переменных, функций, методов, классов - должны быть такими, чтобы код можно было легко читать (и расширять!), не прибегая к дополнительным коментариям для полного понимания процесса.

Comments

[Михаил]

+ магические числа иногда тоже нужно объяснить
короче если смотришь на код и думаешь "че за фигня", там нужны комменты

[Athanor]

Михаил, магические числа стоит помещать в константы, вместо написания комментариев. Если смотришь в код и думаешь "че за фигня", надо рефакторить код, а не писать комментарии.

[Максим Федоров]

Короче можно было написать "не слушать Роберта Мартина"

Answer 3

[Artem Levenkov]

Это не такой простой вопрос, как кажется на первый взгляд.

1. Правильно пишут выше, что не надо путать комментарии и документацию, технически оформленную в виде комментариев.

2. Если рассматривать именно комментарии, то они нужны только вот в каких случаях (по моему опыту):

а) Когда какая-то конвенция дала сбой, но вы все равно решаете не менять ее. Вы в команде договорились, что в данном проекте всегда кладете огнетушитель при входе в помещение в углу слева. Это ваша внутренняя конвенция. Однаком в одном из помещений стены оказываются оранжевого цвета и вы решаете, что на их фоне огнетушитель будет смотреться очень неприметно, и кладете его в нише, которая покрашена в другой цвет. В этом случае надо оставить комментарий, т.к. конвенция нарушена, но это не надо считать ошибкой и в комментарии следует указать причину нарушения.

б) Когда в силу обстоятельств приходится нарушить ожидаемое для всех поведение. Один из огнетушителей имеет слишком тугой курок. Его следует заменить, однако сроки поставки не позволяют вам сделать это до ближайшего релиза. Поэтому вы кладете рядом с огнетушителем трубу, которую следует использовать как рычаг, насадив на курок, и в комментарии указываете причину такого отклонения от ожидаемого поведения и метод применения workaround'а.

Все остальные случаи на мой взгляд при ближайшем рассмотрении либо укладываются в эти два, либо являются примером плохой работы.

Answer 4

[SVM]

Не учите меня программировать.
Комментарии лишними не бывают.

// Когда я начинал это писать, только Бог и я понимали, что я делаю
// Сейчас остался только Бог

// иногда мне кажется, что компилятор игнорирует все мои комментарии

// пьян, исправить позже

// Магия. Не трогать.

/**
 * Всегда возвращает true.
 */
public boolean isAvailable() {
    return false;
}

Comments

[Lander]

/**
 * Всегда возвращает true.
 */
public boolean isAvailable() {
    return false;
}

Это топ! :)

[SVM]

Lander,
Когда то давно попадала эта статья с комментами, думал уже не найду :(
Нагуглил в Яндексе, оказалось что она была на хабре Самые смешные комментарии в исходном коде
оттуда и скопипастил )))
там ещё можно почитать комменты к публикации