Цитата Роберта К. Мартина вырвана из контекста. Вот цитата с немного большим контекстом:
Ничто не может быть настолько полезным, как удачный комментарий. Ничто не может загромождать модуль больше, чем легкомысленные догматические комментарии. Ничто не может быть настолько разрушительным, как старый грубый комментарий, который распространяет ложь и дезинформацию.
Комментарии не похожи на список Шиндлера. Они не "чисто хорошие". Действительно, комментарии в лучшем случае являются неизбежным злом. Если бы наши языки программирования были достаточно выразительными, или если бы у нас был талант тонко владеть этими языками, чтобы выразить свое намерение, нам бы не понадобились комментарии очень сильно - возможно, вовсе нет.
Правильное использование комментариев должно компенсировать нашу неспособность выразить себя в коде. Обратите внимание, что я использовал слово сбой. Я имел в виду это. Комментарии всегда неудачи. Мы должны иметь их, потому что мы не всегда можем понять, как выразить себя без них, но их использование не является поводом для празднования.
Поэтому, когда вы окажетесь в ситуации, когда вам нужно написать комментарий, продумайте его и посмотрите, нет ли какого-либо способа перевернуть таблицы и выразить себя в коде. Каждый раз, когда вы выражаете себя в коде, вы должны погладить себя по спине. Каждый раз, когда вы пишете комментарий, вы должны гримасничать и чувствовать недостаток своей способности выражать мысли.
(Скопировано здесь , но оригинальная цитата взята из Чистого кода: Справочник по мастерству гибкого программного обеспечения )
То, как эта цитата превращается в «Комментарии - всегда неудачи», является хорошим примером того, как некоторые люди вычтут разумную цитату из контекста и превратят ее в глупую догму.
Документация API (например, javadoc) должна документировать API, чтобы пользователь мог использовать его, не читая исходный код . Таким образом, в этом случае документация должна объяснить, что делает метод. Теперь вы можете утверждать, что «Извлечение продукта по его идентификатору» является избыточным, потому что оно уже указано именем метода, но информация, которая nullможет быть возвращена, определенно важна для документа, поскольку это ни в коей мере не очевидно.
Если вы хотите избежать необходимости комментария, вы должны устранить основную проблему (которая является использованием nullв качестве допустимого возвращаемого значения), сделав API более явным. Например, вы можете вернуть какой-то Option<Product>тип, так что сигнатура типа сама четко сообщает, что будет возвращено в случае, если продукт не найден.
Но в любом случае нереально полностью документировать API только через имена методов и сигнатуры типов. Используйте doc-комментарии для любой дополнительной неочевидной информации, которую должен знать пользователь. Взять хотя бы документацию по API из DateTime.AddMonths()BCL:
Метод AddMonths вычисляет итоговый месяц и год с учетом високосных годов и количества дней в месяце, а затем корректирует дневную часть результирующего объекта DateTime. Если результирующий день не является действительным днем в результирующем месяце, используется последний действительный день результирующего месяца. Например, 31 марта + 1 месяц = 30 апреля. Часть времени дня в результирующем объекте DateTime остается такой же, как этот экземпляр.
Невозможно выразить это, используя только имя метода и подпись! Конечно, документация вашего класса может не требовать такого уровня детализации, это всего лишь пример.
Встроенные комментарии тоже неплохие.
Плохие комментарии - это плохо. Например, комментарии, которые только объясняют, что можно тривиально увидеть из кода, классический пример:
// increment x by one
x++;
Комментарии, которые объясняют что-то, что можно прояснить, переименовывая переменную или метод или иным образом реструктурируя код, являются запахом кода:
// data1 is the collection of tasks which failed during execution
var data1 = getData1();
Вот такие комментарии Мартин против. Комментарий является признаком невозможности написания понятного кода - в этом случае использовать понятные имена для переменных и методов. Сам комментарий, конечно, не проблема, проблема в том, что нам нужен комментарий, чтобы понять код.
Но комментарии должны использоваться для объяснения всего, что не очевидно из кода, например, почему код написан определенным неочевидным способом:
// need to reset foo before calling bar due to a bug in the foo component.
foo.reset()
foo.bar();
Комментарии, которые объясняют, что делает излишне запутанный фрагмент кода, также являются запахом, но исправление не должно запрещать комментарии, исправление - это исправление кода! На самом деле, запутанный код действительно существует (надеюсь, только временно, пока не произойдет рефакторинг), но ни один обычный разработчик не пишет идеально чистый код с первого раза. Когда происходит запутанный код, гораздо лучше написать комментарий, объясняющий, что он делает, чем не писать комментарий. Этот комментарий также облегчит рефакторинг позже.
Иногда код неизбежно сложен. Это может быть сложный алгоритм или код, жертвующий ясностью по соображениям производительности. Снова комментарии необходимы.