Как вы документируете свои стандарты кодирования?

Question

Что вы считаете лучшим способом опубликовать ваши стандарты кодирования и почему?

Answer 1

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

ИМХО все, что нужно, чтобы доказать, что это существующий код, который показывает, какой стиль / стандарт.

Путешествуй налегке!

Answer 2

Если вы разрабатываете в .NET. Я бы порекомендовал использовать StyleCop для проверки ваших сборок. Я также рекомендовал бы использовать ReSharper и плагин StyleCop.

С ReSharper и плагином StyleCop вы получаете красные «волнистые» строки под кодом, который не соответствует стандарту, и простая наведение мыши объяснит почему Нет обзоров кода, нет документации к maintian.

Использование StyleCop в процессе сборки гарантирует, что весь проверенный код соответствует стандартам.

Answer 3

Единственный эффективный способ опубликовать стандарт кодирования, на мой взгляд, - это интегрировать его в идеал, используемый разработчиками (например, затмение или идея). Таким образом, новый код будет соответствовать стандартам сразу после установки, а старый код может быть переформатирован с использованием ide.

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

Answer 4

Мы помещаем это в вики со ссылками на фрагменты кода, где это полезно.

Затем мы настроили средство форматирования кода в Eclipse так, чтобы оно максимально соответствовало этому стандарту кодирования, хотя это не может помочь при использовании наилучших методологий кодирования.

Answer 5

Если вы имеете в виду Руководство по стилю - документ Word или PDF. IMO, это то, что «заложено в камень», но для каждого отдельного проекта (если вы видите что-то, что не работает, исправьте это для следующего проекта, особенно если он опаздывает в проекте и у вас есть тонна кода, который следует существующему стилю).

Answer 6

Всякий раз, когда я отвечаю за установление стандарта кодирования, я стараюсь найти в Интернете хороший, который соответствует нашим потребностям, и использую его. Я возьму любой формат, обычно в формате PDF или Word.

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

Answer 7

Мы сделали следующее для документирования наших стандартов кодирования:

1. Записал их в виде простого слова. Основой для этого руководства по стилю были Sun Coding Conventions.
2. Сконфигурированный Checkstyle и PMD, чтобы следовать этим соглашениям о кодировании, дополнительно обеспечил рабочее пространство по умолчанию для Eclipse, которое имело правильную конфигурацию, которая соответствует определенным конфигурациям Checkstyle и PMD.
3. Добавлены три главы к нашим соглашениям о кодировании, в которых объясняется, какие настройки Checkstyle, PMD и Eclipse полностью заполнили какую-либо часть руководства по стилю, чтобы каждый архитектор мог изменить руководство по стилю и конфигурации Checkstyle, PMD и Eclipse.
4. Разработаны маленькие плагины, так что, устанавливая Checkstyle и PMD вместе с нашими плагинами, наше соглашение о кодировании, определенное в Checkstyle и PMD, было по умолчанию и легко выбиралось.

Мы считаем, что это очень помогает не только записать его, но и интегрировать в среду разработки. С другой стороны, мы делаем это только для Eclpise, потому что это слишком много, если вы хотите этого для каждой IDE на земле.

Answer 8

Мы используем следующее:

1. Инструменты / плагины в редакторе (checkstyle, pmd, внутренние инструменты)
2. Проверка времени сборки создает отчет.
3. Вики используется для документирования комментариев к коду
4. Начиная с 3, мы затем реорганизуем «инструментальные» инструменты во внутренний инструмент.

Answer 9

Я думаю, что лучший способ - использовать Checkstyle для обеспечения соблюдения вашего стандарта кодирования и обеспечения сбоя сборки, если какой-то код противоречит правилам checkstyle.

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

Вы также можете настроить вики-страницу.

Answer 10

Я делаю все, чтобы облегчить применение для всех:

• Прежде всего, все в команде должны согласиться применять их
• Я делюсь настройками для используемых редакторов (gvim, emacs ...)
• Я предоставляю пустой исходный файл с заголовком шаблона
• Я обобщаю стандарт на одном справочный лист, не показывая правила, но кусок кода правильно отформатирован как стандартизированный