[Moscow.pm] Комментарии

[Yuri Pats]

2010/3/11 Иван Бессарабов <ivan на bessarabov.ru>:
> Расскажите пожалуйста, как вы относитесь к комментариям в коде? Как вы
> считаете, они помогают или мешают? А сами пишете?

Привет. Комментарии это хорошо.

1. Перед объявлением функции я пишу небольшое описание, что она
делает. Если ф-я вызывается извне модуля (модуль наследуется или
подключается), то  прилагаю пример где и как вызывается. Оформление в
стиле POD.
В большинстве случаев формулировка краткого описания очень помогает и
при реализации, и при отчетности (на daily meetings, например), и при
последующей поддержке кода.

2. Входные параметры проверяются Params::Validate или аналогичным
способом и сразу видно, что и как передается параметрами.

3. Комментировать каждую строчку нет смысла. Там где есть тяжелая
логика, то ее должно описывать ТЗ. Но, в любом случае, для
использования ф-ии необходимо только знать кратко что она делает, как
вызывается и что отдает.
Багфиксинг -- отдельная история. Зачастую приходится ковырять историю
VCS и писать комментарии самому :)

4. Тесты, unit-тестов сам не писал, но для тестирования отдельных
функций, был случай, когда тесты к моему коду писал другой
программист.

-- 
WBR, Yuri Pats