вторник, сентября 23, 2008

Комментарии и код

В одном из предыдущих постов vinler задал вопрос о комментариях в коде. Я начал отвечать и понял, что тема интересная, и тянет на отдельный пост.
Итак вопрос:
Не мог бы ты высказаться по поводу вида комментариев в коде? Я так думаю, это не маловажная часть правил кодирования.
В частности очень интересует твое мнение, нужно ли вести прямо в коде историю изменений и сохранять имена авторов, если файл с момента создания находится под системой контроля версий.
Еще народ очень любит оставлять куски закомментированного кода. С поясненем, что так уже пробовали и это не сработало.


Есть распространенное мнение о том, что хорошему коду комментарии не нужны. И это действительно так. Другое дело, что хорошего кода не так уж много. Поэтому моя точка зрения: не можешь писать хороший код - пиши комментарии.
Не всегда удается написать хороший код. Иногда просто не хватает времени на проработку дизайна, кажется "потом переделаю", но "потом" обычно не наступает никогда. Иногда программисту просто не хватает опыта, чтобы разработать хороший дизайн. В этом случае очень полезно попытаться написать стандартные (для компилятора C#) комментарии к своим классам. После попытки сформулировать короткое описание класса часто наступает "просветление", после которого удается взглянуть на свой код по новому и подправить дизайн. Сам не раз ловил себя на таком.
Другая хорошая привычка, если уж ты чувствуешь в своем коде какой-то smell, но в силу каких-то причин ты не можешь им заняться прямо сейчас, напиши прямо в коде что-то вроде "//здесь воняет". Возможно потом это станет той последней каплей, которая перевесит чашу весов и ты почининишь этот код.
Одни из главных врагов читаемости кода, это невнятное именование и нарушение SRP (Single Responsibility Principle). Основные порождаемые ими проблемы, это невозможность понять по имени класса или метода что они делают, и невозможность отыскать нужный класс или метод. Есть такой парадокс: почти всегда мы считаем свой код хорошим и читаемым, а чужой плохим и невнятным. Происходит это от того, что о своем коде мы всегда знаем больше, чем о чужом. Поэтому никогда не повредит снабдить комментариями свои классы и ключевые методы.
Ну и на конец, если ты пишешь библиотеку для повторного использования, будь добр, прокоментируй публичные контракты всех своих классов. по моему это признак зрелости программиста и проявление уважения к своим коллегам.

Теперь по поводу ведения истории кода прямо в коде. Никогда не удалять старый код, а окружать его комментариями, вести многоэтажные заголовки файлов исходников с копирайтами и персональными списками изменений - все это полный маразм. Проверено, это не работает, и со временем просто превращает код в помойку. По моему это делают те, кто не умеет пользоваться системами контроля версий. Любая СКВ позволяет все это делать намного лучше и удобнее. Единственная полезная практика, сопровождать короткими коментами с номером бага или тикета свои изменения в старом коде (и то это ИМХО - мне так удобно).

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

14 комментариев:

Unknown комментирует...

Еще иногда в ревью используют директиву #warning <...> или #error - тоже в шарпе, естественно.

Sergey Rozovik комментирует...

Да. Ну это уже крайние меры...

Sergey комментирует...

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

Meowth комментирует...

В комментариях (да и не только) достаточно следовать принципу DRY - don't repeat yourself. Если тебе есть что сказать, неочевидное из твоего кода человеку в 10 раз менее разбирающемуся, - стоит это написать.

Идея "//здесь воняет" очень понравилась, сам использую "//fixme: бла-бла, что именно не нравится"

Еще убивал бы за интерфейсы без единой строки комментария - стоит указать как минимум "роль" и назначение каждого метода, значение каждого аргумента.

Еще неплохой прием, после которого 50% комментариев в коде становятся не нужны - это комментарии у приватных членов класса/объекта, поясняющие их роль.

У МакКоннелла в его "Совершенном коде" (Code Complete) отлично указывается еще на несколько приемов и мест комментирования, здорово упрощающих дальнейшую работу

Livce комментирует...

#warning подходит как нельзя лучше для review кода. При написании кода сверху вниз, от глобального к локальному, очень удобно вставлять эту директиву. Если забудите дописать код, то уж коллеги не дадут Вам расслабиться.

Sergey Rozovik комментирует...

Я недавно ревьюил один солющен. Нашел там #warning-и, поставленные архитектором, который уволился три года назад. А ворнинги все живут :)

Igor комментирует...

У меня пользуется конструкция:

// WTF: blablabla

и решарперовский to-do list постоянно на виду. Это держит в тонусе :)

Анонимный комментирует...

блин ну что за //fixme или //воняет или еще какой бред!

ставим
// TODO: _описание_
потом в visualstudio в панели Task List (ну меню View->Task List) выбираем в выпадающем списке Comments
и вуаля - VS увидела ваши тудушки и двойным кликом можно туда и перейти

Meowth комментирует...

Уважаемый Анонимный, про //TODO: я не говорю, потому что "TODO" - это отметка об отстутствии функционала. А как пометить, что функционал есть, но реализация не нравится?
Как по мне, в TODO: удобно вести список текущих задач по коду; проблемные места лучше помечать особо

Livce комментирует...

Когда у нас в команде Архитектор находит #warning-и после очередного релиза, начинается "разбор полётов".

Igor комментирует...

Флейм-вопрос:

А как по вашему философия комментирования кода вяжется с TDD? :) Странно, что вы не коснулись этого аспекта

Sergey Rozovik комментирует...

Флейм-ответ: ИМХО это ортогональные вещи. Потому и не коснулся :)

Анонимный комментирует...

>> потом в visualstudio в панели Task List

0_o
Неужто VS единственная IDE, и во всем нужно на неё опираться ?
ИМХО, не так уж важно TODO, FIXME или "воняет". Важнее, чтобы соответствовало конвенции, принятой в вашей команде( фирме ).

Анонимный комментирует...

да уж.