@Arbil

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

Всем привет

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

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

Так как я начинающий программист самоучка и у меня очень мало опыта, я не знаю кому верить. Правда ли что если к коду нужны комментарии, то он не совсем качественный или же к коду нужно оформлять комментарии
  • Вопрос задан
  • 333 просмотра
Решения вопроса 3
inoise
@inoise
Solution Architect, AWS Certified, Serverless
Давайте перестанем путать комментарии в коде и документацию. Если первое предназначено для объяснения как это вообще работает, то второе ставит перед собой цель описания интерфейса взаимодействия, краткие описания с примерами использования и другие вещи, позволяющие, например, автоматически генерировать документацию
Ответ написан
xmoonlight
@xmoonlight
https://sitecoder.blogspot.com
Комментарии в коде необходимы только в случаях:
1. Класс - в самом начале: его краткое описание и назначение.
2. Метод - если названия и переменных метода недостаточно для понимания его функционирования.
3. Места, где трудночитаемый код: этажерки условий, запросов к БД, и подобные.

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

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

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

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

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

Все остальные случаи на мой взгляд при ближайшем рассмотрении либо укладываются в эти два, либо являются примером плохой работы.
Ответ написан
Пригласить эксперта
Ответы на вопрос 2
sotvm
@sotvm
Умный поймёт , а дураку и так всё равно.
Не учите меня программировать.
Комментарии лишними не бывают.
5e30e1be57646442252796.gif
// Когда я начинал это писать, только Бог и я понимали, что я делаю
// Сейчас остался только Бог


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


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

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

/**
 * Всегда возвращает true.
 */
public boolean isAvailable() {
    return false;
}
Ответ написан
BojackHorseman
@BojackHorseman
...в творческом отпуске...
Правда ли что если к коду нужны комментарии, то он не совсем качественный

неправда.
или же к коду нужно оформлять комментарии

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

Войдите, чтобы написать ответ

Войти через центр авторизации
Похожие вопросы
08 апр. 2020, в 21:19
10000 руб./за проект
08 апр. 2020, в 20:18
35000 руб./за проект
08 апр. 2020, в 19:41
2000 руб./за проект