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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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