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

 Всем привет   

  

Я читал книгу "Чистый код" авторства Роберта Мартина   

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

  

И в данный момент читаю книгу "Совершенный код" авторства Стива Макконнелла  

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

  

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

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

 Комментарии в коде необходимы только в случаях:  

1. Класс - в самом начале: его краткое описание и назначение.  

2. Метод - если названия и переменных метода недостаточно для понимания его функционирования.  

3. Места, где трудночитаемый код: этажерки условий, запросов к БД, и подобные.  

  

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

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

  

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

  

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

  

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

  

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

  

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

 Не учите меня программировать.   

Комментарии лишними не бывают.  

![5e30e1be57646442252796.gif](https://habrastorage.org/webt/5e/30/e1/5e30e1be57646442252796.gif)   

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

  

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

  

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

  

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

  

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

> Правда ли что если к коду нужны комментарии, то он не совсем качественный

  

неправда.  

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

  

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