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

[Вячеслав Матюхин]

On Mar 11, 2010, at 11:04, Иван Бессарабов wrote:
> Расскажите пожалуйста, как вы относитесь к комментариям в коде? Как вы
> считаете, они помогают или мешают? А сами пишете?
> 
> Очень интересно узнать ваше мнение и заранее спасибо за ответы =)

В PODе всегда стараюсь описать каждый публичный метод, плюс всегда NAME/SYNOPSIS/SEE ALSO/AUTHOR.
В случае с бинарниками, помимо манов, из SYNOPSIS еще и --help получается, если Pod::Usage использовать.

Для новых модулей стараюсь писать тест на pod coverage (с использованием Pod::Coverage::CountParents, иначе невозможно).

POD стараюсь пересекать с кодом.
То есть я уверен, что все остальные способы просто не работают, очень легко поправить код и не поправить документацию, если POD находится в конце файла (а зачастую вообще не помнишь, задокументирован данный конкретный модуль в проекте, или нет).
Вообще, контекстность - это очень важное свойство документации-в-комментах, оно повышает кешхит в головах разработчиков. Можно, конечно, организовать отдельную группу людей, которые будут писать техническую документацию, но это очень неэффективно, и результат всегда будет неполным и неактуальным.
Хотя не всем такой подход нравится: http://blogs.perl.org/users/mike_friedman/2010/03/separation-of-concerns.html

В инлайновых комментариях пишу всякие случайные пометки, полагаясь на интуицию, так что я не уверен, что они всегда полезны другим людям, которые читают мой код. Но мне вроде помогают.
В них же пишу TODO и FIXME.
С TODO и FIXME та же ситуация, что и с POD'ом, вроде бы внешний багтрекер лучше (доступнее другим разработчикам, универсальнее, более функционален), но в нем потерян контекст.

PS: В чужом коде комментарии, естественно, всегда приветствуются :)