Привет всем!
Поставила дома и на работе 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_>Так сказать заметки на полях, где грабли лежат, где были сложности, и то что важно но сложно сразу выудить из кода.
