Що повинно бути в хорошому (читати: корисному) стандарті кодування?
Відповіді:
Причини кожної вимоги. Таким чином, дотримання стандарту не стає своєрідним культом вантажу, і люди знають, що нормально змінювати стандарт, якщо причина цього більше не застосовується, або порушувати стандарт у конкретних випадках, коли причина явно не застосовується .
Вкладки проти просторів! Я отримую божевільні оновлення, коли хтось із моїх колег випадково робить багато вкладок, щоб пробіли перемістилися у сховище
Названня конвенцій
EDIT: Під цим я маю на увазі називання Правил, а не називання Правил.
Наприклад, Посібник буде All boolean values should begin with Is/Can/Has/etc when possible. Правило було бAll boolean values must start with Is
IsCanUpdateі IsHasChildren. Звичайно, це неправильно, але це було постановлено в стандарті. І це моя думка: щойно ви починаєте конкретизувати ці речі, ви повинні переконатися, що ви охоплюєте всі основи, інакше люди натрапляють на те, що стандарт не покриває, або погано прикривають, і тоді вони або пишуть щось, що не так, або вони починають ігнорувати стандарт. Так чи інакше, команда програє.
Стандарт кодування для групи повинен містити параметри компілятора попереджень та помилок, які необхідно усунути.
Програмісти повинні вільно збільшувати попередження щодо власного коду, але має бути базовий рівень, щоб читання та робота з чужим кодом не захаращувала вихід, отриманий від компілятора.
Такий стандарт також повинен стосуватися того, як програмісти можуть відключати такі попередження в кожному конкретному випадку, якщо є винятковий фрагмент коду, який інакше не відповідає.
Мені подобаються деякі стандарти (я знаю, що їх дуже багато, але саме такі я віддаю перевагу):
Кодування стандарти допомагають трохи , коли ви пишете код в перший раз, вони допомагають багато , коли ви або ваша заміні, повинні оновити код через 2 роки.
Ідеальний стандарт призводить до коду, де ви можете перейти на будь-яку довільну сторінку в коді та зрозуміти, що це робиться під час першого читання, оскільки
З іншого боку, занадто багато довільних стандартів можуть порушити потік написання коду. Тому я вважаю, що кожен елемент запропонованої конвенції про кодування повинен бути оцінений відповідно до цих двох критеріїв:
Якщо жодне з них не відповідає дійсності, пункт є просто довільним і, ймовірно, непотрібним
Я б включив у стандарт, про який пишу:
Для ясності:
Організація файлів: Визначення фіксованого порядку для елементів у файлі дозволяє команді легко орієнтуватися по інших файлах. Вам не доведеться шукати #defines або визначення структур.
Конвенції про іменування: Послідовна читальність посібників для читання. Але уникайте занадто конкретизувати занадто багато правил, що шкодить для запису.
Структура коду Фігурне розміщення дужок, рівні відступи, пробіли проти вкладок тощо. Так, це може бути сильним особистим уподобанням, але мета - чіткий код. Знайдіть найкращий варіант для команди та дотримуйтесь її.
Для коректності:
Найкращі практики, характерні для вашого типу проблеми: Правила щодо розподілу пам'яті, одночасності чи переносимості.
"Коректність коректування", правильне використання staticта volatileін.
Правила щодо макросів препроцесора та інших особливостей мови, що легко зловживаються.
Що має бути у стандарті кодування? Якнайменше. Менше швидше. І з виправданням, будь ласка.
Не тому, що я якийсь ковбойський кодер, який не бажає ніякого процесу, а тому, що я бачив важкі специфікації кодування без логіки позаду цього (мабуть) "Я знайшов це в" Мережі десь ще в 95 році ", що в кінцевому підсумку стає бюрократичний кошмар, з яким потрібно працювати.
Деякі люди, чесно, вірять, що, скачуючи стандарти, вони побачать відповідне збільшення коду "якості" і, можливо, завдяки такому міру вони будуть. Тим часом вони ігнорують архітектуру, продуктивність, здоровий глузд і купу інших речей, які в кінцевому рахунку мають значення більше, ніж кількість рядків у файлі.
Якийсь добрий старий здоровий глузд не змириться; є занадто багато стандартних документів для кодування, які працюють на невідповідних точках (такі елементи, як тип і розмір шрифту, є одними з найбільш крайніх, які я бачив).
Найкраще робити, якщо ви знаходитесь у групі розробників, - поговорити один з одним і переглянути свій код, сформулювати консенсус щодо того, що прийнятно, і якщо вам потрібно записати основні моменти як рекомендації, але зберігайте їх як саме ці вказівки. Якщо ви не можете виправдати будь-які розбіжності з настановами, ви дійсно повинні врахувати, чому ви це робите.
Зрештою, чіткий і зрозумілий код важливіший за будь-яке жорстке правило щодо верстки чи типографії.
Як уже згадували інші, важливим є покриття тесту кодом. Мені також подобається бачити:
Структура проекту Чи є тести частиною коду чи вони знаходяться в окремому проекті / пакеті / каталозі? Чи відповідає код інтерфейсу користувача із резервними матеріалами? Якщо ні, то як це розділяється?
Процес розвитку. Пишіть тести перед кодом? Чи виправлення зламаних складок має пріоритет над розвитком? Коли проводяться огляди коду, і що вони повинні охоплювати?
Управління вихідним кодом. Що потрапляє до реєстрації, коли? Чи контролюються документи дизайну та плани тестування? Коли ви здійснюєте відділення та коли тегуєте? Чи зберігаєте ви попередні версії, і якщо так, то скільки / на скільки часу?
Норми розгортання. Як складається упаковка? Що потрібно перейти до нотаток до випуску? Як створюються / контролюються / запускаються сценарії оновлення?
Забудьте про все лайно щодо називання конвенцій, форматування та кількості рядків у функції / методі / модулі. Одне правило: використовуйте будь-який існуючий стиль у тому, що ви редагуєте. Якщо вам не подобається чийсь стиль, виберіть його в огляді коду. Єдиним винятком може бути річ "вкладки проти просторів", хоча б тому, що багато редакторів / IDE сліпо перетворюють один в інший, а потім ви закінчуєте, знищуючи історію змін, тому що кожен рядок був змінений.
Я думаю, що насправді слід вирішити дві речі, і я насправді розглядаю їх окремо, тому що до них не можна підійти однаково, хоча я вважаю, що обидва важливі.
Технічний аспект я кваліфікую за стандартом кодування , як і Герб Саттер та Андрій Олександреску з ними стандартами кодування C ++ . У презентації я кваліфікуюсь із стилю кодування , який включає умовні позначення, відступ тощо ...
Стандарт кодування
Оскільки він є суто технічним, Стандарт кодування може бути переважно об'єктивним. Як таке, кожне правило повинно підтримуватися причиною. У книзі, про яку я згадував кожен предмет, є:
Обґрунтування та винятки дуже важливі, оскільки вони узагальнюють, чому і коли.
Заголовок має бути чітким, що під час оглядів потрібно мати лише список заголовків (шпаргалка), з якими можна працювати. І очевидно, групуйте елементи за категоріями, щоб легше було доглядати за одним.
Саттеру та Олександреску вдалося скласти список із лише сотні предметів, хоча C ++ вважається волохатим;)
Стиль кодування
Ця частина, як правило, менш об'єктивна (і може бути прямо суб'єктивною). Наміром тут є гарантувати послідовність, оскільки це допомагає обслуговуючим особам та новим бажаючим.
Ви не хочете входити у священну війну щодо того, який тип відступу чи дужки краще тут, є форуми для цього: тож у цій категорії ви робите речі консенсусом> голосування більшості> довільне рішення лідера.
Для прикладу форматування дивіться список варіантів художнього стилю . В ідеалі правила повинні бути чіткими та досконалими, щоб програма могла переписати код (хоча навряд чи ви коли-небудь кодуєте його);)
Для умови іменування я б спробував зробити клас / типи легко відрізнити від змінних / атрибутів.
Також до цієї категорії я класифікую такі "заходи", як:
Різне?
І, як остаточне слово, є один пункт, який рідко, якщо взагалі, обговорюється в Стандартах кодування, можливо, тому що це особливе для кожної програми: організація коду. Архітектурне питання, мабуть, найвидатніший випуск, задумайте над початковим дизайном, і ви будете мучитися ним через роки. Вам, можливо, слід додати розділ для основної обробки файлів: державні / приватні заголовки, управління залежностями, розділення проблем, взаємодія з іншими системами або бібліотеками ...
Але це нічого, якщо їх фактично не застосовують і не застосовують .
Будь-яке порушення повинно бути порушено під час перегляду коду, і жодне перегляд коду не повинно бути нормальним, якщо порушення виявлено:
Очевидно, що зміна правила означає отримати «йти вперед» від лідерів.
Мені подобається формат у Радянських рекомендаціях щодо дизайну, він включає загальний розділ та раціональні рекомендації. Найкорисніший біт - це деталі, які починаються з Do, Do Not, Avoid та uzeti на думку.
Ось приклад у розділі " Впровадження членів інтерфейсу". Явно в ньому є такі пункти (зауважте, я відмовився від обгрунтування заради стислості)
Уникайте явного впровадження членів інтерфейсу, не маючи на це вагомих причин
Розглянемо можливість чіткого впровадження членів інтерфейсу, якщо учасники призначені для виклику лише через інтерфейс.
Не використовуйте явних членів як межу безпеки.
Як забезпечити захищений віртуальний елемент , який має ту ж функціональність , як> явно реалізованого члена , якщо є в виду функціональні можливості спеціалізуватися похідними класами.
Це створює хороший загальний тон. Використовуючи Avoid and Think, ви можете дозволити розробникам використовувати їх судження. Також тому, що вони керуються правилами, а не правилами розробників, швидше за все, вважають їх більш приємними і, в свою чергу, більше шансів дотримуватися їх.
Здається, ніхто не згадував про безпеку - у стандарті кодування ви повинні мати посилання на вимоги захищеного коду (наприклад, використання модулів перевірки вводу, заборона відомих слабких функцій, таких як strcpy, вимоги обробки помилок тощо)
Приклади. Акуратно розташовані, нетривіальні, близькі до реального приклади, які використовують кожне правило. Коментарі (не обов'язково частина коду), яка частина прикладу слідує за правилом.
Шаблони. Не вид C ++, а щось копіювати та вставляти наживо. Набагато простіше отримати ці коментарі з котла на 24 рядках прямо тоді, коли у вас є посилання на копіювання.
Особливість номер один: максимум дві сторінки.
Це те, що хоче кожен розробник читати і запам’ятовувати. Вам не доведеться шукати стандарт у кожному випадку, коли потрібно писати нову функцію (або, ще гірше, новий рядок). Отже, тримайте це коротко і дотримуйтесь лише тих правил, які дійсно надають підвищену цінність для кінцевого продукту.
Стандарти кодування дійсно кілька предметів:
Умови кодування
Кращі практики
для екс. Ніколи не залишайте порожній Catch після спроби
try { Foo(); } catch { //do nothing }
1) Якщо виняток, викинутий Foo (), може спричинити інші проблеми функцій, які випливають, які припускають, що foo був успішним.
2) Глобальний обробник помилок не сповістить команду підтримки про виняток, коли це відбувається у продажі
Середовище кодування
Стандарти кодування, коли вони написані на папері, лише настільки ефективні. Мені подобається, як Go публікує свій стандарт кодування. Він має інструмент gofmtдля форматування тексту програми у формат. Будь-які дебати щодо формату кодування тоді просто спричинить виправлення джерелgofmt .
Що стосується формату,
if функціональне тіло, блоки операторів для будь-яких інших цілей,Коли я читаю чужий код (здебільшого мова С), якщо назви змінних / функцій не є інтуїтивно зрозумілими в контексті проекту або якщо він перевищує п’ять рівнів відступу або функції приймають більше шести або семи аргументів або функція працює над дві або три сторінки на екрані, стає дуже важко читати і розуміти код. Коли його попросять виконати роботи з удосконалення / обслуговування, це лише додасть труднощів. Це змушує мене хотіти, gofmtщоб програма була написана для кожного проекту (або навіть мови), і кожен файл вихідного коду запускався через цю програму, перш ніж вона буде вчинена в проекті.
Мені подобається посібник зі стилів Google JavaScript .
У його керівних принципах ще є деталі, якщо вони потрібні.