Что вы нашли, чтобы быть лучшим способом опубликовать свои стандарты кодирования и почему?
Если вы имеете в виду Style Guidelines - документ Word или PDF. IMO, это то, что "заложено в камне", но на основе каждого проекта (если вы видите что-то, что не работает, исправьте его для следующего проекта, особенно если он задерживается в проекте, и у вас есть тонна кода, который следует существующему стилю).
Мы используем наш код для документирования стандартного. Это наряду с принудительным выполнением от старших/ведущих инженеров отлично поработало для нас. Причина, по которой мы не поддерживаем фактический документ, состоит в том, что мы обнаружили, что никто не читает его, и он устарел довольно быстро.
ИМХО все, что требуется, чтобы доказать, что существует существующий код, который показывает, что стиль/стандарт.
Свет для путешествия!
Если вы работаете в .NET. Я бы рекомендовал использовать StyleCop для проверки ваших сборок. Я бы также рекомендовал использовать ReSharper и плагин StyleCop.
С ReSharper и плагином StyleCop вы получите красные "squiggly" линии под кодом, который против стандарта и простая мышь, объяснят почему. Нет обзоров кода, нет документов для maintian.
Использование StyleCop в процессе сборки гарантирует, что все проверки кода соответствуют стандартам.
Единственным эффективным способом публикации стандарта кодирования, на мой взгляд, является его интеграция в идее, используемую разработчиками (например, eclipse или идея). Таким образом, новый код будет следовать стандартам из коробки, а старый код может быть переформатирован с помощью ide.
Только немногие разработчики будут читать стандарты кодирования, меньшее из них будет использовать их впоследствии...
Мы помещаем его в wiki, со ссылками на фрагменты кода, где это полезно.
Затем мы создаем форматировщик кода в Eclipse, чтобы соответствовать как можно ближе к этому стандарту кодирования, хотя это не может помочь в передовых методах кодирования.
Когда я отвечаю за установку стандарта кодирования, я стараюсь найти хороший в Интернете, который соответствует нашим потребностям и использует его. Я возьму любой формат, в который он входит, обычно PDF или Word.
Нет смысла повторно изобретать колесо - я могу также использовать тяжелую работу, которую кто-то еще сделал.
Я думаю, что лучший способ - использовать Checkstyle для обеспечения соблюдения вашего стандарта кодирования и гарантировать, что сборка завершится неудачей, если какой-то код что-то противоречит правилам проверки.
Затем используйте обзор кода и парное программирование, чтобы юниоры могли учиться у пожилых людей
Вы также можете настроить страницу вики.
Мы используем следующее:
Для документирования наших стандартов кодирования мы сделали следующее:
Мы считаем, что это помогает не только записать его, но и интегрировать в среду разработки. С другой стороны, мы делаем это только для Eclpise, потому что это слишком много сделать, если вы хотите, чтобы для каждой IDE на земле.
Наш проект в основном написан на python, поэтому мы в основном приняли Python Coding Guidelines, изменили что-то здесь и там, что нам не понравилось, и закрепили их на нашей Trac wiki. Он связан прямо на первой странице, чтобы разработчики знали, где его найти. До сих пор он действительно выполнял довольно приличную работу:
Руководящие принципы кода - это общеорганизационный документ, описывающий практику. И он доступен и должен строго соблюдаться.
Стандарт форматирования кода может быть определен между членами команды (или проекта). Для нашего проекта он хранится в SVN как набор настроек для Resharper плагин.
Для начального процесса вики, подготовленные с подзаголовками, полезны для сбора мнений от разных разработчиков. После того, как полученная обратная связь будет собрана, ее можно затем убрать и "опубликовать".
UPDATE:
Несколько лет спустя, а Google Docs теперь служит своего рода вики.
Я документирую код стандарта:
( или ))Когда мне удалось создать небольшую команду, наши "стандарты кодирования" были оберткой script в CVS, которая выполняла отступ (с общим файлом rc в командной строке), когда вы его проверяли.
Создается собственный веб-сайт с SVN, используемый для управления изменениями. "Последняя" всегда доступна для команды онлайн.
Мы перешли из документов Word, которые оказались громоздкими и склонными к устареванию
N.B. Также у нас есть клиент, который не использует что-либо в стороне от самой сборки в цикле CI. Они сохраняют свои правила в ReSharper и довольны результатами
Если вы используете Eclipse, вы можете использовать formatters (Preferences- > Java- > Code Style- > Formatters) для автоматического форматирования кода при сохранении исходного файла. Мы просто используем наш форматировщик нашей вики, и каждый импортирует его в Eclipse.
Прохладная вещь о форматировщиках заключается в том, что вы можете решить, какой из них вы хотите использовать, чтобы иметь разные проекты в разных форматах. Однако мы обычно используем только один формат, чтобы наш код был единообразным во всех проектах.
Это зависит от обстоятельств:
Я работал в небольшой компании с тремя разработчиками. Там мы просто выговорили. Это означает не что иное, как просить ваших со-разработчиков, если вы сомневаетесь в стиле кодирования. Через некоторое время кто-то понял, что одни и те же вопросы задавались несколько раз и открывали страницу с кодировкой в нашей вики.
Сегодня я работаю в небольшой исследовательской лаборатории. В этой конкретной области у нас нет формальные стандарты кодирования. Однако, поскольку мы работаем в командах и регулярно проводим пару сессий, неявный стандарт кодирования появляется из ниоткуда.
От некоторых друзей, которые разрабатывают системы для управления самолетами, я знаю, что они согласны с стандартами кодирования на основе
Этот стандарт кодирования записывается и выполняется с помощью QA.
В настоящее время у нас есть стандарт кодирования в Wiki, который имеют права только для редактирования. Однако, как многие люди уже заявили, никто не читает его после первых нескольких дней. В настоящее время мы пытаемся получить наш стандарт кодирования в StyleCop на стороне .NET. Материал Delphi немного сложнее, так как у нас нет среды Delphi, такой как StyleCop.
Я делаю все, чтобы упростить подачу заявки для всех: