Стандартный документ

Question

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

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

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

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

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

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

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

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

Answer 1

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

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

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

Answer 2

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

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

if(...)
{

}

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

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

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

while(stillwaiting())
{
   ;
}

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

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

-Адам

Answer 3

Я поддержу предложение Джейсона.

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

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

Надеюсь, что получится!

Answer 4

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