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: В чужом коде комментарии, естественно, всегда приветствуются :) -- Moscow.pm mailing list [email protected] | http://moscow.pm.org
