Когда комментарии "слишком много", а когда их недостаточно?

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

Я всегда очень придерживался практики, когда я комментирую верхнюю часть каждого файла с помощью базового блока комментариев, комментирует каждое определение метода/класса/etc, а затем комментирую любое место в коде, где, я думаю, могу прийти назад через 6 месяцев и подумайте про себя: "WTF".

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

Ответ 1

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

Я просто укажу вам на Джефф Атвуд замечательный пост по теме, который поражает гвоздь прямо на голове.

Ответ 2

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

Ответ 3

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

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

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

Ответ 4

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

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

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

Ответ 5

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

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

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

Ответ 6

Этот вопрос, как правило, обсуждается много, но вот мои US $0.02 по теме:

Я бы предпочел увидеть слишком много комментариев, чем не достаточно. В противном случае вы всегда можете удалить лишние комментарии из кода; однако вы не можете извлечь из них смысл, если их не существует.
Я слышал, что некоторые разработчики утверждают, что другие разработчики, которые "за документ" (определения этого отличаются от человека), их код не являются хорошими разработчиками. Говоря, что вы обновляете счетчик, может быть признаком того, что вы не знаете, что делаете, имея четкое руководство к какой-либо бизнес-логике, сидящей там в середине метода, над которым вы работаете, может быть весьма полезным.
Несмотря на то, что есть отличные разработчики, которые могут писать исключительно четкий код, который не требует комментариев, большинство разработчиков не так хороши или они тратят больше времени на создание кода для самостоятельной документации, чем если бы они были включая пару комментариев.
Вы не знаете уровень навыка следующего человека, чтобы прочитать свой код, и если используемые вами языковые конструкции могут сбивать с толку, обычно рекомендуется добавить комментарий, который кто-то может использовать в Google с помощью учебника.

Ответ 7

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

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

Ответ 8

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

Ответ 9

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