Когда комментарии “слишком много”, и когда они недостаточно? [закрытый]

За всю свою карьеру я ни разу не встречал того чудесного зверя «самодокументирующегося кода». Может, мне просто не повезло, но я начинаю подозревать, что этого на самом деле не существует.

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

Как правило, я бы прокомментировал только общедоступные API и сложные для понимания алгоритмы.

Не используйте комментарии, чтобы объяснить, что вы сделали - это то, для чего предназначен код, используйте комментарии, чтобы объяснить, почему вы это сделали.

Эта тема часто обсуждается, но вот мои 0,02 доллара США по этому поводу:

1. Я бы предпочел видеть слишком много комментариев, чем недостаточно. Если у вас что-то не получается, вы всегда можете удалить лишние комментарии из кода; однако вы не сможете извлечь из них смысл, если их там изначально не было.
2. Я слышал, как некоторые разработчики утверждали, что другие разработчики, которые "слишком документируют" (определения этого понятия зависят от человека) свой код, не являются хорошими разработчиками. Хотя заявление о том, что вы обновляете счетчик, может быть признаком того, что вы не знаете, что делаете, наличие четкого руководства по некоторой бизнес-логике, расположенной в середине метода, над которым вы работаете, может быть весьма полезным.
3. Хотя есть несколько отличных разработчиков, которые могут написать очень понятный код, не требующий комментариев, большинство разработчиков не настолько хороши, или они тратят больше времени на написание кода, чтобы он был самодокументирующимся, чем если бы они просто включили пару комментариев.
4. Вы не знаете уровень квалификации того, кто будет читать ваш код, и если языковые конструкции, которые вы используете, могут быть запутанными, то обычно хорошей идеей является включение комментария, который кто-то может использовать для поиска учебника.

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

Диомидис Спинеллис только что написал хорошую колонку для IEEE column (цитируется в его блоге), излагая проблему и несколько решений:

При комментировании мы всегда находимся в паре мы всегда находимся в паре нажатий клавиш от катастрофы: переформулировать функцию кода на английском языке. И вот тут-то и начинаются проблемы начинаются.

Что бы я хотелось бы видеть в комментариях объяснение, почему метод, который очевиден и намного проще, чем метод, использованный в коде, не работает.

Это уже обсуждалось до смерти.

Я просто отсылаю вас к замечательному посту Джеффа Этвуда на эту тему , который бьет в самую точку.

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

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

• Если вы действительно великий гуру кода, не утруждайте свой божественный код лишними комментариями.
• Если вы почти не знаете, что делаете, постарайтесь задокументировать свои грубые попытки, чтобы другие могли попытаться спасти беспорядок.
• Если вы средний (а большинство из нас таковы по определению), то оставьте несколько подсказок в комментариях для себя и других, чтобы упростить задачу во время технического обслуживания, но не оскорбляйте чей-то интеллект и не тратьте место, документируя ДЕЙСТВИТЕЛЬНО очевидное. В идеале ваши комментарии должны описывать ваш код на мета-уровне, указывая не то, что вы делаете, а почему. Также как, если вы делаете что-то необычное или сложное.

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

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

Очень четко написанный код с хорошими идентификаторами - материал, который иногда называют «самодокументированным» - прекрасно иллюстрирует, что делает код. Это нормально, насколько это возможно. Задача комментариев - объяснить , почему .