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

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

Ответы

Ответ 1

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

Ответ 2

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

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

Свет для путешествия!

Ответ 3

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

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

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

Ответ 4

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

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

Ответ 5

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

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

Ответ 6

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

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

Ответ 7

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

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

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

Ответ 8

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

  • Инструменты/плагины в редакторе (checkstyle, pmd, внутренние инструменты)
  • Сроки выполнения времени создают отчет.
  • Вики используются для документирования комментариев к просмотру кода
  • Начиная с 3, мы затем реорганизуем "инструментальные" в собственный инструмент.

Ответ 9

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

  • Написал их в текстовом файле. Основой для этого styleguide были конвенции кодирования солнца.
  • Конфигурированный Checkstyle и PMD, чтобы следовать этим соглашениям кодирования, дополнительно предоставили рабочее пространство по умолчанию для Eclipse, которое имело правильную конфигурацию, которая соответствует определенным конфигурациям Checkstyle и PMD.
  • Добавлены три главы к нашим соглашениям о кодировании, в которых объясняется, что Checkstyle, PMD и Eclipse полностью заполняют часть стилей, так что каждый архитектор мог бы изменить стиль и конфигурации Checkstyle, PMD и Eclipse.
  • Разработал небольшие плагины, чтобы, установив Checkstyle и PMD вместе с нашими плагинами, наше соглашение о кодировании, определенное Checkstyle и PMD, было по умолчанию и легко поддается выбору.

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

Ответ 10

Наш проект в основном написан на python, поэтому мы в основном приняли Python Coding Guidelines, изменили что-то здесь и там, что нам не понравилось, и закрепили их на нашей Trac wiki. Он связан прямо на первой странице, чтобы разработчики знали, где его найти. До сих пор он действительно выполнял довольно приличную работу:

Ответ 11

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

Стандарт форматирования кода может быть определен между членами команды (или проекта). Для нашего проекта он хранится в SVN как набор настроек для Resharper плагин.

Ответ 12

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

UPDATE:

Несколько лет спустя, а Google Docs теперь служит своего рода вики.

Ответ 13

Я документирую код стандарта:

  • структура из наиболее важного общего стиля (например, отступы, обертка строк, фигурные скобки,...)
  • к менее видимым деталям (пробел до/после ( или ))
  • примеры кода
  • описания параметров для настройки форматирования кода eclipse
  • Проса

Ответ 14

Когда мне удалось создать небольшую команду, наши "стандарты кодирования" были оберткой script в CVS, которая выполняла отступ (с общим файлом rc в командной строке), когда вы его проверяли.

Ответ 15

Создается собственный веб-сайт с SVN, используемый для управления изменениями. "Последняя" всегда доступна для команды онлайн.

Ответ 16

Мы перешли из документов Word, которые оказались громоздкими и склонными к устареванию

  • Страницы Wiki со стандартами и примерами
  • Стандартные инструменты проверки стандартного кодирования, работающие в процессе CI

N.B. Также у нас есть клиент, который не использует что-либо в стороне от самой сборки в цикле CI. Они сохраняют свои правила в ReSharper и довольны результатами

Ответ 17

Если вы используете Eclipse, вы можете использовать formatters (Preferences- > Java- > Code Style- > Formatters) для автоматического форматирования кода при сохранении исходного файла. Мы просто используем наш форматировщик нашей вики, и каждый импортирует его в Eclipse.

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

Ответ 18

Это зависит от обстоятельств:

Я работал в небольшой компании с тремя разработчиками. Там мы просто выговорили. Это означает не что иное, как просить ваших со-разработчиков, если вы сомневаетесь в стиле кодирования. Через некоторое время кто-то понял, что одни и те же вопросы задавались несколько раз и открывали страницу с кодировкой в ​​нашей вики.

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


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

  • безопасность и правительственные ограничения
  • потребности и материалы отдела QA
  • если есть свобода выбора: вход от разработчиков

Этот стандарт кодирования записывается и выполняется с помощью QA.

Ответ 19

В настоящее время у нас есть стандарт кодирования в Wiki, который имеют права только для редактирования. Однако, как многие люди уже заявили, никто не читает его после первых нескольких дней. В настоящее время мы пытаемся получить наш стандарт кодирования в StyleCop на стороне .NET. Материал Delphi немного сложнее, так как у нас нет среды Delphi, такой как StyleCop.

Ответ 20

Я делаю все, чтобы упростить подачу заявки для всех:

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