Привет всем!
Поставила дома и на работе StyleCop, натравила на свой проект — для каждого класса, метода он пишет, что те должны иметь header, т. е. /// summary. Я так понимаю, что по умолчанию эта штука будет требовать документировать абсолютно любой файл, класс, метод, свойство и пр. А что Вы документируете?
Здравствуйте, Lloyd, Вы писали:
L>чтобы просто от StyleCop-а отмазаться или реально пишете осмысленный комментарий?
Если комментарии на английском, то можно использовать GhostDoc. Он умеет парсить идентификаторы, выкусывая шаблонные словосочетания, скажем, «TestWorldModel» снабжает комментарием «Tests model of the world». Плюс умеет копипастить комментарии из интерфейсов, вставляет комментарии в духе Капитана Очевидность для конструкторов, etc. Говорят, Решарпер умеет делать то же самое.
Здравствуйте, XJess, Вы писали:
XJ>Поставила дома и на работе StyleCop, натравила на свой проект — для каждого класса, метода он пишет, что те должны иметь header, т. е. /// summary. Я так понимаю, что по умолчанию эта штука будет требовать документировать абсолютно любой файл, класс, метод, свойство и пр.
Если поставить максимальный уровень предупреждений и указать в проекте «генерировать XML-документацию», то сам компилятор будет выдавать предупреждения, без всяких StyleCop'ов.
XJ>А что Вы документируете?
Я настроил TreatWarningsAsErrors для предупреждений о документирующих XML-комментариях на сервере интеграции, так что теперь приходится документировать всё публичное.
Здравствуйте, Qbit86, Вы писали:
Q>Если комментарии на английском, то можно использовать GhostDoc. Он умеет парсить идентификаторы, выкусывая шаблонные словосочетания, скажем, «TestWorldModel» снабжает комментарием «Tests model of the world». Плюс умеет копипастить комментарии из интерфейсов, вставляет комментарии в духе Капитана Очевидность для конструкторов, etc. Говорят, Решарпер умеет делать то же самое.
И чего ради "пыль в глаза пускать"? Может сразу признаться, что не пишете и отключить это рул нафик?
Здравствуйте, Qbit86, Вы писали:
L>>И чего ради "пыль в глаза пускать"? Может сразу признаться, что не пишете и отключить это рул нафик?
Q>Нет, мы пишем. Правда, по-русски, так что пользы от GhostDoc'а не очень много. По этим комментариям потом chm-документация генерится.
И что, ею пользуются? Или у вас такое требование заказчика?
Здравствуйте, Lloyd, Вы писали:
Q>>...По этим комментариям потом chm-документация генерится.
L>И что, ею пользуются? Или у вас такое требование заказчика?
Chm-документация — требование заказчика. Собственно документирование API — внутреннее требование. Куда удобнее написать один раз внятный комментарий, чем каждому члену команды объяснять в Скайпе суть параметров метода или назначение интерфейса.
Здравствуйте, Qbit86, Вы писали:
L>>И что, ею пользуются? Или у вас такое требование заказчика?
Q>Chm-документация — требование заказчика. Собственно документирование API — внутреннее требование. Куда удобнее написать один раз внятный комментарий, чем каждому члену команды объяснять в Скайпе суть параметров метода или назначение интерфейса.
А из кода это не проще понять? Иногда даже msdn сливает рефлектору в плане полезности.
Q>А у вас что, API не документируют?
Нет, у нас не настолько болшая команда, нет необходимости.
Здравствуйте, Lloyd, Вы писали:
L>А из кода это не проще понять?
Из общих соображений — у пользователя API исходного кода может и не быть. В любом случае, приятно видеть summary и список перегрузок во всплывающей подсказке во время вызова, без перехода к определению и вникания в код.
L>Иногда даже msdn сливает рефлектору в плане полезности. :)
Иногда. Но transaction cost велик.
Q>>А у вас что, API не документируют? L>Нет, у нас не настолько большая команда, нет необходимости.
Здравствуйте, Qbit86, Вы писали:
L>>А из кода это не проще понять?
Q>Из общих соображений — у пользователя API исходного кода может и не быть. В любом случае, приятно видеть summary
Конечно приятно, но вопрос то не в этом, а в том, оправдывает ли это затраченные усилия.
Q>и список перегрузок во всплывающей подсказке во время вызова, без перехода к определению и вникания в код.
Перегрузки и так показываются.
L>>Иногда даже msdn сливает рефлектору в плане полезности.
Q>Иногда. Но transaction cost велик.
Что ты имеешь в виду?
Q>>>А у вас что, API не документируют? L>>Нет, у нас не настолько большая команда, нет необходимости.
Q>Команда меньше двух человек?
Здравствуйте, Lloyd, Вы писали:
L>>>Иногда даже msdn сливает рефлектору в плане полезности. :) Q>>Иногда. Но transaction cost велик. L>Что ты имеешь в виду?
Здравствуйте, Qbit86, Вы писали:
L>>>>Иногда даже msdn сливает рефлектору в плане полезности. Q>>>Иногда. Но transaction cost велик. L>>Что ты имеешь в виду?
Q>Optimize transaction costs.
Я знаю, что такое transaction, но не понимаю, как это относится к тому, что "Иногда даже msdn сливает рефлектору в плане полезности".
Здравствуйте, Lloyd, Вы писали:
L>Я знаю, что такое transaction, но не понимаю, как это относится к тому, что "Иногда даже msdn сливает рефлектору в плане полезности".
Я к тому, что затраты на «свериться с документацией» (т.е. не основная, промежуточная, часто выполняемая операция) в случае Рефлектора в сотни раз больше, чем в случае полноценной документации, доступ к которой на расстоянии одного-двух кликов.
Здравствуйте, Qbit86, Вы писали:
Q>Я к тому, что затраты на «свериться с документацией» (т.е. не основная, промежуточная, часто выполняемая операция) в случае Рефлектора в сотни раз больше, чем в случае полноценной документации, доступ к которой на расстоянии одного-двух кликов.
Полноценная документация это хорошо. Только ее еще надо написать.
Но к полноценной документации нельзя отнести текст который только повторяет названия функций и параметров но только слова разделены пробелами. Если не плпнируется chm делать, то более полезны коментарии описывающие только неочевидности. Так сказать заметки на полях, где грабли лежат, где были сложности, и то что важно но сложно сразу выудить из кода.
Здравствуйте, Silver_s, Вы писали:
S_>Так сказать заметки на полях, где грабли лежат, где были сложности, и то что важно но сложно сразу выудить из кода.
Здравствуйте, XJess, Вы писали:
XJ>Поставила дома и на работе StyleCop, натравила на свой проект — для каждого класса, метода он пишет, что те должны иметь header, т. е. /// summary. Я так понимаю, что по умолчанию эта штука будет требовать документировать абсолютно любой файл, класс, метод, свойство и пр. А что Вы документируете?
То, что требуется в каждом конкретном случае. СтайлКоп — лишь инструмент, который необходимо настроить так, как требуется вам, а не образец, под который следует подстраиваться.
Прим этом, ко многим, на первый взгляд, не очевидным, его предупреждениям стоит относиться очень серьёздно (например, об явном указании IFormatProvider там, где можно). И только крепко подумав и осознав, к чему может привести отключение (или, наоборот, не отключение) правила, принять то или иное решение. Для этого помогает курение и медитация над описаниями правил и поиск и прочтение обсуждений правил в тырнетах.
Help will always be given at Hogwarts to those who ask for it.
StyleCop используем, но процентов на 35-40.Комментарии, точки в описаниях,порядок методов/свойств,именование переменных. Вкупе с checkin policy
сильно помогает.
Здравствуйте, XJess, Вы писали:
XJ>Привет всем! XJ>Поставила дома и на работе StyleCop, натравила на свой проект — для каждого класса, метода он пишет, что те должны иметь header, т. е. /// summary. Я так понимаю, что по умолчанию эта штука будет требовать документировать абсолютно любой файл, класс, метод, свойство и пр. А что Вы документируете?
Все что требует StyleCop — все и комментируем. Отключено только правило запрещающее region в методах.
Сейчас осматривая здоровый такой распределенный сервис с кучей компонент — очень рад, что было такое правило.
Дело в том, что обязательное правило комментрования иногда заставляет писать тавтологию в комментариях, но зато это же правило:
1. Заставляет писать что-то полезное гораздо чаще (если уж начали писать комментарии и есть что полезного написать — то оно будет написано).
2. Стимулирует сам процесс написания и поддержки комментариев (написать комментарий — это не что-то из ряда вон выходящее чему только в книжках учат, а а стандартная часть процесса).
3. Заставляет рефакторить код. Я лично несколько раз с отвращением прекращал писать комментарий и шел пить кофе и думать, как лучше написать код, чтобы такие комментарии оставлять не приходилось.
Здравствуйте, Кэр, Вы писали:
Кэр>3. Заставляет рефакторить код. Я лично несколько раз с отвращением прекращал писать комментарий и шел пить кофе и думать, как лучше написать код, чтобы такие комментарии оставлять не приходилось.
Так и есть. Неоднократно замечал при написании коммента к функции что она слишком много делает и знает, и вообще "всемогутор" получается — в итоге рефакторинг и более простой и понятный код. Происходит этакое внутреннее code review.
А вообще, написание комментов себя реально окупает через пару месяцев. В итоге у нас код без комметариев просто не пройдет code review, а подобный код в продакшене реально может запороть performance review и отложить повышение на полгода/год. Тем более что задалбывает это только первое время. Потом как-то втягиваешься и начинаешь еще при создании функции продумывать как ты ее назначение объяснишь в комментах.
