Стандарт документов - PullRequest
       6

Стандарт документов

5 голосов
/ 06 сентября 2008

Я пишу документ по стандартам кодирования для команды из примерно 15 разработчиков с проектной нагрузкой от 10 до 15 проектов в год. Среди других разделов (которые я могу публиковать здесь по мере их поступления) я пишу раздел о форматировании кода. Поэтому, для начала, я думаю, что по какой-то причине мы устанавливаем некоторые базовые, согласованные стандарты форматирования / именования кода.

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

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

  • Как вы заключаете в скобки? Соблюдаете ли вы те же рекомендации в скобках при работе с классами, методами, пытаетесь использовать блоки catch, операторы switch, if else и т. Д.

  • Вы выстраиваете поля в столбце? Вы записываете / префикс частных переменных с подчеркиванием? Соблюдаете ли вы какие-либо соглашения об именах, чтобы упростить поиск сведений в файле? Как вы заказываете членов вашего класса?

Как насчет предложений для пространств имен, упаковки или стандартов папок с исходным кодом / организации? Я склонен начинать с чего-то вроде:

<com|org|...>.<company>.<app>.<layer>.<function>.ClassName

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

Ответы [ 4 ]

3 голосов
/ 07 сентября 2008

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

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

if(...)
{

}

Все переключатели / выбранные имеют регистр по умолчанию. Случай по умолчанию регистрирует ошибку, если это неверный путь.

По той же причине, что и выше, любые управляющие структуры if ... elseif ... ДОЛЖНЫ заканчиваться значением по умолчанию else, которое также регистрирует ошибку, если это неверный путь. Один оператор if не требует этого.

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

while(stillwaiting())
{
   ;
}

Стандарты именования имеют очень разные стили для определения типов, определенных констант, глобальных переменных модуля и т. Д. Имена переменных включают тип. Вы можете посмотреть на имя и иметь представление о том, к какому модулю оно относится, его области действия и типу. Это позволяет легко обнаруживать ошибки, связанные с типами и т. Д.

Есть и другие, но это верх моей головы.

-Adam

3 голосов
/ 07 сентября 2008

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

Если вы используете язык с существующим стандартом (например, Java, C #), его проще всего использовать или, по крайней мере, начать с него в качестве первого черновика. Sun много думала об их правилах форматирования; Вы могли бы также воспользоваться этим.

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

2 голосов
/ 07 сентября 2008

Я иду ко второму предложению Джейсона.

Я только что закончил документ по стандартам для команды из 10-12 человек, которая работает в основном на Perl. В документе говорится об использовании «перлитидоподобного отступа для сложных структур данных». Мы также предоставили всем примерные настройки perltidy, которые очистили бы их код для соответствия этому стандарту. Это был очень понятный и очень стандартный отраслевой стандарт для языка, поэтому команда отлично его оценила.

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

Надеюсь, это сработает!

1 голос
/ 06 сентября 2008

Очевидно, что это зависит от языков и технологий. Судя по вашему примеру пространства имен, я собираюсь угадать Java, и в этом случае http://java.sun.com/docs/codeconv/ - действительно хорошее место для начала. Возможно, вы захотите взглянуть на что-то вроде стандартной структуры каталогов maven, которая сделает все ваши проекты похожими.

...