В какой момент настройки Stylecop перестают быть полезными и начинают раздражать?

Question

Я работаю в команде, где мы используем обширный набор правил в StyleCop, и мне интересно, что вы думаете по поводу общей точки зрения, когда такой инструмент перестает быть полезным и начинает раздражать.Мы также используем GhostDoc, поэтому код пронизан комментариями XML, что делает код намного сложнее для чтения и, следовательно, для просмотра.У меня нет проблем с комментариями XML, и я нахожу их очень полезными в некоторых местах, но действительно ли они нужны для каждого поля и свойства?

У нас есть замечательная цель: «у каждого проекта должно быть 0 предупрежденийкогда построено ", но, конечно, эта цель должна соответствовать разумному набору правил StyleCop, иначе ценное время будет потрачено впустую на" устранение "причины предупреждений StyleCop.

Какие мысли по этому поводу?

РЕДАКТИРОВАТЬ Теперь мне действительно интересно, каков аргумент для такого инструмента, как stylecop вообще?Почему бы не бросить это и позволить разумным стандартам кодирования и хорошим обзорам кода позаботиться обо всем остальном?Особенно в хорошей компетентной команде?Конечно, тогда задача получения 0 предупреждений фактически добавит ценность, поскольку все предупреждения будут актуальны.

Я думаю, что единственным преимуществом GhostDoc является то, что он экономит вам несколько секунд на написание XML-комментария с нуля.Я не думаю, что вы должны принять сгенерированный комментарий, не редактируя его - что может быть контрпродуктивно.

Вот комбинация правила Stylecop (SA1642: ConstructorSummaryDocumentationMustBeginWithStandardText), которое выполняется сгенерированным GhostDoc комментарием xml - добавляет ли любое значение в конце дня?

Answer 1

Я думаю, что это скорее пустяк, чем вопрос, но я согласен с вами в том, что:

• чрезмерно навязанные правила стиля - это плохо.

Хотя очевидно, что должны существовать руководящие принципы для форматирования исходного кода, чрезмерно предписываемые неразрывные правила приводят к неприятным угловым случаям. Строгое соблюдение правил во всех случаях может привести к созданию неоправданно грязного или переутомленного кода.

Кодирование - это разновидность написания, и, как таковое, бонусное правило Оруэлла - «нарушай любое из этих правил раньше, чем говорить что-либо прямо-таки варварское» - необходимо также применить к руководствам по стилю кодирования.

Я скептически отношусь к тому, что автоматическое применение стилей является хорошей идеей в команде компетентных программистов, которые могут устанавливать и понимать руководства по стилю. Автоматические строки полезны для выявления случайных ошибок, но если они применяются в строгих предписывающих законах для форматирования кода, они не могут учитывать правило Оруэлла. С сильным набором правил это может заставить вас писать менее поддерживаемый код под видом ремонтопригодности.

Если в вашей команде есть менее компетентные программисты, чей результат беспорядочный, если не вынуждает их к стилю, тогда применение правил может быть хорошей идеей. (Но тогда у вас, вероятно, есть большие проблемы!)

• автоматизированные комментарии - очень плохая вещь

Я раньше не видел GhostDoc, но на самом деле я немного шокирован.

Сам пример на собственной полосе:

/// <summary>
///     Determines the size of the page buffer.
/// </summary>
/// <param name="initialPageBufferSize">
///     Initial size of the page buffer.
/// </param>
/// <returns></returns>
public int determineBufferSize(int initialPageBufferSize) {

- почти канонический пример плохого комментария, добавляющий абсолютно нулевое понимание кода, который он документирует. Это абсолютно хуже, чем отсутствие комментариев.

Все схемы in-source-doc, которые следовали за Javadoc, время от времени немного подозрительны, поскольку они загромождают исходный код материалами, которые часто предназначены для конечных пользователей - совсем другая аудитория, чем те, кто читает код. Но это абсолютные ямы. Я не могу себе представить, кто думал, что это хорошая идея.

Answer 2

StyleCop - это инструмент .Это не должно быть идеально из коробки, и это не должно отвечать потребностям каждого.

Лично я говорю «Да, это важно» - потому что, когда вы работаете в команде разработчиков, StyleCop помогает вамубедитесь, что ваши правила кодирования соблюдаются.В этом и заключается его цель: оценивать стандарты кодирования автоматически, измеримо и согласованно.Если вам не нужна возможность делать это в процессе сборки, тогда вы правы - это пустая трата времени.

Вы сами говорите: цель нулевых предупреждений "должна быть против разумногоНабор правил StyleCop. "Нет смысла запускать какой-либо инструмент с конфигурацией, которая не соответствует вашим потребностям.Если правило «раздражает» для вас, то отключите его, но для кого-то еще это может быть жизненно важно.

Что касается вашего вопроса «добавляет ли ценность»: да.Люди недооценивают ценность последовательности.Если все ваши конструкторы имеют одинаковый стиль комментария, если все Intellisense для свойств в вашем проекте имеют одинаковую структуру, это будет на одно меньшее умственное препятствие (независимо от того, насколько оно мало).И с инструментами, которые автоматизируют это, это в почти нулевом усилии.На что жаловаться?

Answer 3

Когда на кодирование правила уходит больше времени, чем на то, что вы когда-либо могли получить, сократив поддержку.

Как вы знаете, исправление ошибки занимает намного больше времени, чемнаписав его, вы все равно сможете проделать довольно большую работу, чтобы сделать код более надежным и обслуживаемым, прежде чем достигнете порога.

Answer 4

Крайне важно, чтобы код был хорошо написан и читался / сопровождался, но мы используем помощники по автоматическому форматированию кода Visual Studio и Resharper для нашего кода и AtomineerUtils для хранения комментариев документации XML в строго определенном и аккуратном формате.

В результате основные правила StyleCop не имеют значения, поскольку наш код всегда придерживается важных правил «по умолчанию». Меньшие правила StyleCop, как правило, слишком строги для повседневного использования. (Большинство из этих правил лишь незначительно улучшают качество или удобочитаемость кода, поэтому мы считаем неприемлемой стоимость их соблюдения. Мы предоставляем нашим программистам немного «свободы выражения» - до тех пор, пока их код легко читается другими в команде, мы не возражаем против незначительных изменений в стиле кодирования). Поэтому после оценки StyleCop я не смог найти никакой реальной пользы.

В отличие от этого мы считаем FXCop очень полезным, потому что проблемы, которые он выделяет, связаны не только с незначительными проблемами читабельности - он время от времени выявляет серьезные ошибки и проблемы с производительностью.

Answer 5

Есть несколько пунктов вашего вопроса, которые привлекли мое внимание, поэтому я хотел бы добавить некоторые мысли к предыдущим ответам.

У меня нет проблем с комментариями XML, и я нахожу их очень полезнымиместами, но действительно ли они нужны для каждого поля и свойства?

Некоторые поля и свойства настолько очевидны для всех, что им не нужно объяснение.Например, если класс Coordinate имеет свойства X, Y и Z, в комментариях объяснять нечего.

Но когда речь идет о таком инструменте, как StyleCop, инструмент не может определить разницу между очевидным свойством и свойством, которое может оказаться трудным для понимания при первом обнаружении исходного кода.Поэтому нет, комментарии не нужны везде, но мы либо применяем комментарии к каждому полю и свойству, либо отключаем правило и позволяем разработчику принять решение.

Вот комбинация правила Stylecop (SA1642:ConstructorSummaryDocumentationMustBeginWithStandardText), встречаемый сгенерированным GhostDoc xml-комментарием - добавляет ли какое-либо значение в конце дня?

Каким-то образом.Некоторые инструменты отображают конструкторы так же, как и другие методы, и вы не можете визуально различать их (если вы не помните имя класса).XML-комментарий, с другой стороны, настолько ясен, что очень легко понять, что это конструктор.

Кстати, что бы вы еще здесь написали?

• Что-то еще?Отсутствие стандарта для конструкторов затруднит чтение кода и понимание того, что метод является конструктором в представлениях, где оба отображаются одинаково.

• Нет комментариев вообще?Это может быть решением, так как такой комментарий может быть легко сгенерирован из имени класса.Но это усложнит ситуацию (почему автоматическая генерация комментария для конструкторов, а не для других методов?).Кроме того, если вы не предоставите описание этого конструктора, как кто-то может узнать, что такое someParameter?

---

Наконец, чтобы ответить на ваш вопрос, никто не может сказать, что каждое правило StyleCopвсегда полезно в каждом случае.Но помните, что глупость здесь - это цель "каждый проект должен иметь 0 предупреждений при сборке", а не сам StyleCop .Если вы опытный разработчик и пишете чистый код, нет никаких причин не отключать некоторые правила StyleCop, по крайней мере, если вы хорошо понимаете, что они означают, почему они здесь и каковы будут последствия, чтобы не следовать этому правилу.

В нашей компании есть политика использования StyleCop для каждого проекта, и если в крошечном проекте есть сотни предупреждений, значит, есть проблема.В то же время, У меня часто возникали ситуации, когда я отключал несколько правил StyleCop для целых классов просто потому, что это приведет к напрасной трате времени на их применение и никому ничего не приносит .С другой стороны, мне совсем не понравилось, когда мой коллега отключил FxCop / StyleCop просто , чтобы иметь возможность писать имена классов, методов и свойств на французском языке (я работаю во французской компании, которая такжеработает с англоязычными разработчиками), поэтому я бы сказал, что для некоторых людей оба инструмента должны быть включены каждый раз, без возможности их отключения.

Answer 6

Полезно иметь набор стилей, который используют все, и для нового кода StyleCop обеспечит это для всех.

Но при добавлении StyleCop в существующий проект , который был написан с другим стилем , вы получите сотни, тысячи или десятки тысяч нарушений , что По сути, это произвольные правила , такие как:

• if должен сопровождаться пробелом
• Все параметры функции должны отображаться в одной строке или каждый в отдельной строке
• Однострочные комментарии должны начинаться с пробела
• Поля должны иметь пустую строку между
• За открывающей скобой не должно следовать пустой строки
• имена полей не должны начинаться с подчеркивания или префикса
• Параметр по умолчанию не должен использоваться, вместо него используйте перегрузки
• не префикс местных вызовов с this
• Порядок использования операторов

Просто не имеет смысла редактировать тысячи существующих файлов с сотнями тысяч строк кода только для соблюдения таких правил.

• При любом изменении есть вероятность, что это изменение приведет к ошибкам.
• Если вы не вносите изменения, чтобы исправить ошибки или вводить функции, зачем вы это делаете?

Если ответ «заткнись StyleCop» - и, честно говоря, есть несколько способов сделать это.

Ваша цель должна заключаться в устранении предупреждений, которые не представляют ошибки, чтобы вы могли видеть - и затем исправлять - более проблемные предупреждения, которые могут быть. Наличие 1500 предупреждений о форматировании однострочных комментариев является препятствием, без которого вы можете обойтись.

Следовательно, в устаревшей кодовой базе:

• Отредактируйте набор правил, чтобы отключить любые произвольные стилистические правила с более чем несколькими нарушениями. Это больше проблем, чем стоит: ничего плохого не произойдет, потому что проект использует подчеркивания для полей, но если вы может случайно вызвать конфликт имен, пытаясь это исправить.
• При наличии одного или двух нарушений тщательно продумайте, лучше ли использовать файл подавления, чем редактировать рабочий, проверенный код, просто чтобы скрыть стилистическое предупреждение. Вам не нужно вставлять набор изменений с тысячами пробелов в сотнях файлов. Легко представить разницу в поведении, когда вы думаете, что просто переформатируете блок, и легко пропустить такую ​​вещь, просматривая измененные строки.
• Только если вы уверены, что нарушение правила представляет собой ошибку, вы должны изменить код. Так что, если параметры не находятся в одной строке? Переформатируйте код во что бы то ни стало, если вам нужно понять его прямо сейчас и формат затрудняет это. Но не только потому, что так говорит StyleCop.
• Даже добавление документации по параметрам не обязательно безвредно: Если вы не знаете код наизнанку, вы, возможно, просто запутываетесь в своих собственных заблуждениях для следующего разработчика.