Здравствуйте, 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 и отложить повышение на полгода/год. Тем более что задалбывает это только первое время. Потом как-то втягиваешься и начинаешь еще при создании функции продумывать как ты ее назначение объяснишь в комментах.
