Чому дядько Боб пропонує, щоб стандарти кодування не були записані, якщо ви можете цього уникнути?

Поки я читав це запитання , голосований відповідь цитував дядька Боба щодо стандартів кодування , але мене бентежила ця порада:

3. Не записуйте їх, якщо зможете цього уникнути. Швидше, нехай код буде таким, як приймаються стандарти.

Це відскочило в моєму мозку, але я не міг знайти місця, куди приклеїтись. Якщо нова команда приєднується до команди або змінюються стандарти кодування, чи не може виникнути плутанина інформації?

Чому я не повинен записати стандарт кодування?

Причин декілька.

1. Ніхто не читає документацію.
2. Ніхто не слідкує за документацією, навіть якщо її читають.
3. Ніхто не оновлює документацію, навіть якщо її читають і дотримуються.
4. Написання списку практик набагато менш ефективне, ніж створення культури.

Стандарти кодування - це не те, що люди повинні робити, а про те, що вони насправді роблять. Коли люди відхиляються від стандартів, це слід підбирати та змінювати за допомогою процесу перегляду коду та / або автоматизованих інструментів.

Пам'ятайте, вся суть стандартів кодування полягає в тому, щоб полегшити наше життя. Вони є ярликом для нашого мозку, щоб ми могли відфільтрувати необхідні речі з важливих речей. Набагато краще створити культуру огляду для її виконання, ніж формалізувати її в документі.

Є ще одне тлумачення. Я не вірю, що це мав на увазі дядько Боб, але варто задуматися.

Не захоплюйте стандарти кодування в документ. Захопіть його в коді за допомогою автоматизованого процесу, який підтверджує, що стандарти дотримані .

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

Включіть щось, як Checkstyle, у свій склад. Це може застосувати основні правила, такі як стандарти форматування та іменування, а потім замість того, щоб витрачати розумові зусилля на розгляд стилю, все це можна перевантажити на тупий процес, який, принаймні, гарантовано є ретельним.

Якщо це має значення, то чітко визначте, чого саме ви хочете, і не виправдайте, якщо це неправильно.

Люди нехтують реальною метою документа про стандарти кодування, який полягає у вирішенні суперечок .

Більшість рішень у стандарті кодування матимуть лише незначний вплив на читабельність та продуктивність. Особливо, якщо ви прийняли «нормальний» стиль для мови, і дизайнери мови починають розуміти, що це повинно бути частиною специфікації (наприклад, Go).

Оскільки вони настільки банальні, аргументи можуть по-справжньому нагріватися та працювати нескінченно, завдаючи реального збитку продуктивності та згуртованості команди. Або можна затьмарити історію змін нескінченним переформатуванням між двома або більше уподобаними стилями людей.

Наявність письмового стандарту закінчує аргумент. Керівники можуть вказати на це і відвернути невдоволення щодо документа. Ви можете посперечатися з аркушем паперу, але це не буде слухати вас.

(Див. Також "Тиранія безструктурності" )

Тому що коментарі - брехня .

Стандарт кодування - це великий коментар щодо того, яким повинен бути код. Сам код є кінцевим джерелом істини. Істина в даному випадку - це не поведінка коду, це стиль, в якому вона виражається. Якщо ваші стандарти вже не відображені у вашому коді, вас чекає багато роботи.

Дядько Боб розглядає коментар як особисту невдачу програміста, оскільки це доводить, що йому не вдалося висловити призначення фрагмента коду самою мовою програмування. Аналогічно, стандартний документ - це неспроможність виразити узгоджений стиль у кодовій базі.

Нові програмісти повинні витрачати час на перегляд коду, а не витрачаючи днів на читання документа, що містить багато розділів (мені довелося це зробити, зітхаючи).

Документ про стандарти не така вже й погана ідея, але я був у магазинах програмування, де зберігання стандартних документів було чиєюсь роботою на повний робочий день. Якщо вам потрібно зберегти стандартний документ, збережіть його на сторінці. Але якщо у вас вже є код, невже ніхто не зможе скласти один і той же документ менше ніж за день?

Наявність стандартів коду є важливим. Мати документ, який диктує, якими вони є, це не так.

Чому дядько Боб пропонує, щоб стандарти кодування не були записані, якщо ви можете цього уникнути?

Якщо ви запитуєте причини його думки, то, можливо, у вас є відповідь, лише якщо він опублікує відповідь тут ( наша думка просто не має значення), однак ...

Чому я не повинен записати стандарт кодування?

Якщо ви запитуєте, чи прав він він у цьому?: Дозвольте мені єдиним непопулярним (поки що) сказати, що у вас немає підстав уникати цього.

ЗАПИСЬТЕ ВНИЗ . Однак я спробую пояснити свої причини ...

Девід запропонував у коментарі, що головний пункт відповіді Стівена полягає не в тому, чому ви не повинні писати документи, а в якій формі вони є. Якщо настанови формалізовані в інструментах (а не лише вручну перегляд коду), я можу погодитись (коли закон не вимагає чогось іншого). Зауважте, що, на жаль, інструменти не можуть перевірити все (теорія обчислень не є нашим другом) часто, оскільки вони обмежені певним перекладом або пакетом або будь-якою вашою улюбленою мовою називають кордоном .

Однак формулювання дядька Боба не змушує мене думати, що він про це говорить.

Чи можна погодитися з таким старшим експертом? Я майже для кожного пункту цитованої публікації (подробиці див. Також у другій частині цієї відповіді). Давайте спробуємо розібратися, чому (якщо ви вже знаєте, що вказівки щодо кодування стосуються не лише незначних проблем форматування ).

• За деяких обставин письмові стандарти кодування вимагаються законодавством.
• Я читаю документацію і впевнений, що не один. Члени команди можуть змінюватися з часом, знання не можуть бути в кодовій базі 5-10 років або в думці членів команди. Організації повинні звільняти людей, які не дотримуються внутрішніх вказівок.
• Стандарти кодування після їх затвердження не змінюватимуться часто, і якщо вони хочуть знати про них. Якщо стандарти змінилися, то ваша документація (у коді) застаріла, оскільки весь ваш код не відповідає новому стандарту. Переформатування / рефакторинг може бути повільним, але ви завжди маєте письмове авторитетне керівництво, яке слід дотримуватися.
• Краще прочитати документ на 5 сторінок, ніж перевірити LOC 10 / 20K, щоб екстраполювати правило (яке ви можете зрозуміти неправильно, BTW), без сумніву в цьому.
• Іронічно, що хтось, хто написав багато книг про принципи дизайну та стиль кодування, припускає, що ви не повинні писати власні вказівки, чи не краще, якщо він кинув нас на приклади коду? Ні, тому що письмові вказівки не тільки говорять вам про те, що робити, але й ще дві речі, яких не вистачає коду: що не робити та причини робити це чи ні.

"Безкоштовне самоорганізуюче програмування" добре для ніндзя 16-річного хлопця, але організації мають інші вимоги :

• Якість коду має надаватися (і визначатися) на рівні компанії - це не те, про що може вирішити одна команда. Вони можуть навіть не мати навичок вирішувати, що краще (скільки розробників, наприклад, має всі необхідні навички, щоб переглянути MISRA або навіть просто зрозуміти кожне правило?)
• Учасників можна переміщувати в різних командах: якщо всі дотримуються одних і тих же стандартів кодування, то інтеграція плавна і менш схильна до помилок.
• Якщо команда самоорганізовується, то стандарти змінюватимуться з часом, коли члени команди змінюються - у вас з'явиться величезна база коду, яка не відповідає чинним прийнятим стандартам .

Якщо ви думаєте про людей перед процесом, то я можу запропонувати лише прочитати про TPS: люди є центральною частиною Lean, але процедури сильно формалізовані.

Звичайно, невелика організація, що має лише одну команду, може дозволити команді вирішити стандарти, які слід прийняти, але тоді вони повинні бути записані. Тут, на Programmers.SE, ви можете прочитати повідомлення Еріка Ліпперта: Мабуть, ми всі згодні, що він досвідчений розробник, коли він працював для Microsoft, він повинен був дотримуватися їхніх письмових рекомендацій (навіть якщо деякі правила можуть бути неправильними , не застосовуються чи марними йому.) Що з Джоном Скітом? Вказівки Google досить суворі (і багато людей не згодні з ними), але він повинен дотримуватися таких вказівок. Чи зневажливо ставиться до них? Ні, вони, ймовірно, працювали над визначенням та вдосконаленням таких керівних принципів. Компанію не створює один член (або одна команда), і кожна команда не є островом .

Приклади

• Ви вирішили не використовувати кілька класів успадкування та вкладених класів у C ++, оскільки фактичні члени команди не дуже добре розуміють це . Пізніше той, хто хоче скористатися кількома спадщинами, повинен переглядати весь LM LOC, щоб побачити, чи він коли-небудь використовувався. Це погано, оскільки якщо дизайнерські рішення не документально підтверджені, вам доведеться вивчити цілу базу коду, щоб їх зрозуміти. І навіть тоді, якщо він не використовувався, це тому, що він суперечить стандарту кодування, або це дозволено, але просто не було жодних раніше ситуацій, коли багатократне успадкування було добре підходить?
• У C # у вас були перевантажені методи надання параметрів за замовчуванням, оскільки база вашого коду запускалася, коли в C # не були доступні додаткові параметри. Потім ви змінилися, і ви почали їх використовувати (рефакторинг старого коду, щоб використовувати їх щоразу, коли вам доводилося змінювати такі функції). Ще пізніше ви вирішили, що необов'язкові параметри погані, і ви починаєте уникати їх використання. Яке правило підказує ваш код? Це погано, тому що стандарт еволюціонує, але кодова база розвивається повільніше, і якщо це ваша документація, значить, у вас виникають проблеми.
• Джон перейшов з команди А в команду Б. Джон повинен вивчити новий стандарт; під час навчання він, ймовірно, введе більш тонкі помилки (або, якщо пощастить, просто знадобиться багато часу, щоб зрозуміти існуючий код і зробити перегляд коду довше).
• Команда A переходить до кодової бази, яка раніше належала команді B. У неї є зовсім інші стандарти кодування. Переписати? Адаптувати? Змішати? Усі вони однаково погані.

Дядько Боб

Нехай вони розвиваються протягом перших кількох ітерацій.

Щоправда, поки у вас немає стандарту, і ваша організація не поставила вам завдання створити його.

Нехай вони будуть конкретними для команди, а не для компанії.

Ні, з усіх пояснених вище причин. Навіть якщо ви думаєте формалізувати просто форматування коду (найменш корисна річ, яку ви, можливо, хочете формалізувати), у мене все ще є пам'ять про нескінченні (і марні) війни щодо форматування. Я не хочу жити їм знову і знову, встановлюйте це раз на раз.

Не записуйте їх, якщо зможете цього уникнути. Швидше, нехай код буде таким, як приймаються стандарти.

Ні, з усіх пояснених вище причин (звичайно, якщо ви не будете переробляти весь код за один знімок, коли зміни керівних принципів) Ви хочете залишити свій код таким, який є? Як ви перевіряєте кодову базу, щоб зрозуміти поточні вказівки? Пошук за віком файлу та адаптація стилю кодування до віку вихідного файлу?

Не приймайте закон про хороший дизайн. (наприклад, не кажіть людям не користуватися goto)

Щоправда, вказівки повинні бути короткими, і ніхто їх не буде читати. Не повторюйте очевидного.

Переконайтесь, що всі знають, що стандарт стосується спілкування, і нічого іншого.

Не тільки, хороший стандарт - це якість, якщо ви не хочете мати стандарт лише про незначні деталі.

Після перших кількох ітерацій зберіть команду разом, щоб прийняти рішення.

Дивіться перший пункт і не забувайте, що стандарт кодування - це звичайно процес, який потребував багатьох років, щоб розробити і вдосконалити: мало ітерацій, можливо, з молодшими розробниками? Дійсно? Ви хочете покластися на пам'ять одного старшого (за наявності) члена?

Три ноти:

• На мою думку, недоліки в деяких мовах серйозніші, ніж інші, наприклад, у C ++ стандарт компанії на рівні компанії навіть потрібніший, ніж у Java.
• Це міркування може не застосовуватися повністю (а причини дядька Боба можуть бути менш крайніми ), якщо ви працюєте в дуже невеликій компанії, де у вас є лише одна невелика команда.
• Вас найняли (як команда), і ви будете працювати наодинці з одним новим проектом, тоді ви забудете його і продовжуєте рухатися далі. У цьому випадку ви можете не байдуже (але ваш роботодавець повинен ...)

1. Щоб бути корисним, стандарт кодування не повинен говорити про сутнісні питання; тільки питання стилю. У ньому слід вказати лише ті речі, які є довільними та неоднозначними. наприклад розміщення дужок, глибина відступу, пробіли проти вкладок, умовні позначення імен тощо.
2. Питання стилю локальні, а не глобальні. Кожна команда повинна сприймати свій своєрідний стиль, відповідно до свого завдання та своєї особистості. Це забезпечує збереження стандартів простим і легким вагою. Корпоративні стандарти перевантажуються усіма можливими міркуваннями, конфігураціями та винятками.
3. У команді єдиною причиною написання окремого документа стилю кодування є те, якщо код, створений командою, не відповідає стандарту. У такому випадку у вас немає стандарту. Для ефективності стандарт повинен бути виражений самим кодом. І якщо це так, немає необхідності в окремому документі.
4. У застарілих системах команди та стилі змінюються з часом. У цьому немає нічого поганого. Старий код матиме старіший стиль. Новіший код матиме новіший стиль. Команда повинна знати про стилі та їх вік. Щоразу, коли пишеться новий код, він повинен бути в новому стилі, незалежно від того, де в коді він знаходиться.

Чому я не повинен записати стандарт кодування?

Причин для цього багато. Ось деякі міркування:

1. Скільки часу люди витрачають на "вивчення" стандартів коду, щоб мати багато часу, щоб вся команда переглядала, обговорювала, документувала, переглядала ... тощо. Це як постійно обговорювати свій "Посібник з працівниками" - як часто це входить у порядок денний зустрічі команди ??

2. Коли проект захищається / зберігається / тощо. то кілька людей, які залишаються, зазвичай не можуть продовжувати дотримуватись (або, можливо, навіть не читали) стандартів. Наступне, що ви знаєте, всі ці зусилля, щоб "зберегти код чистим", все-таки були витрачені на багато.

3. Якщо проектні кіоски або принесе нове керівництво, велика ймовірність, що людина повністю ігнорує попередні правила і захоче зробити це по-новому. Знову ж, що було отримано кодифікаційними стандартами ??

Ви повинні обов’язково прочитати №6:

Після перших кількох ітерацій зберіть команду разом, щоб прийняти рішення.

Іншими словами, коли прийшов час розпочати проект, просто на деякий час піти з потоком. Потім обговоріть загальні правила стандартів кодування, якими користується нинішня команда, і в основному дотримуйтесь їх. Таким чином, ви максимізуєте зусилля, спрямовані на вдосконалення продукту, мінімізуючи зусилля, необхідні для написання, перегляду та документування "синтаксичного цукру", який увійшов до отримання виконуваного коду.

Дуже мало команд отримують величезні переваги від стандартів кодування. Зазвичай "читабельність" є надто розпливчастою - і більшість розробників не отримують великої користі від точних правил проміжку, нових рядків тощо, але ви можете уникати постійно дратувати розробників, маючи принаймні кілька правил.

Ще одна відповідь, яка, на мою думку, не була викладена досить чітко, це те, що це також означає, що люди сліпо дотримуються правил. Це означає, що люди повинні придумати фактичні обгрунтування своїх дизайнерських рішень та конвенцій кодування, а не лише залежно від того, що це було записано для його обгрунтування.

По-перше, наскільки я знаю, дядько Боб - людина Яви, це дуже важливо для розуміння того, що він говорить.

Під час роботи в команді Java або C #, якщо поточний код був написаний досвідченими розробниками, мені легко підібрати стиль кодування і не відставати від нього. Якщо я не бажаю цього робити, можливо, я не був потрібною людиною для роботи ... Якщо немає перегляду коду чи програмування пари, щоб забрати мене, коли я не дотримуюся стилю, то компанія має більша проблема, ніж те, як я називаю поля учасників!

Як Java, так і C #, а також більшість сучасних мов, були визначені таким чином, що програмісту може потрапити кілька «простих» пасток.

Однак коли я почав програмувати, я використовував C (а пізніше C ++). На C ви можете написати код типу

if (a = 3);
{
   /* spend a long time debugging this */
}

Компілятор не помилиться, і це важко помітити, читаючи багато коду. Однак якщо ви пишете:

if (3 = a)
{
   /* looks odd, but makes sense */
}

Компілятор видає помилку, і мені легко змінити код на 3 == a. Так само, якщо стандарт кодування не дозволяє =використовуватись в ifумові або "порожньому ifоператорі", тоді перевірку коду можна використовувати як частину системи збирання для відстеження цієї помилки.

Мої погляди на стандарти кодування сильно змінилися, коли я відійшов від C / C ++: Мені подобалося, що стандарти кодування, які суворо виконуються, і багато сторінок. Тепер я думаю, що вам потрібно лише перелічити використовувані інструменти та отримати неофіційну угоду між початковими членами команди щодо декількох конвенцій про іменування. Ми більше не живемо у світі команд з понад 30 розробників, які пишуть заявки на C / C ++ ...

Є причина, що мені ніколи не подобався JScript, і я думаю, що TypeScript - це найкраще, що трапляється з веб-розробкою протягом багатьох років. Я думаю, що розробникам веб-інтерфейсу все ще потрібні стандарти кодування через дефекти в дизайні HTML / CSS / JScript тощо.

Наявність джерела стандарту кодування самодокументування означає дві речі.

1. Люди повинні проконсультувати базу коду та переглянути її, щоб стати досвідченими учасниками. Це неймовірно важливо. Читання інструкцій з кодування - це марна трата часу в порівнянні з зануренням у кодову базу.
2. Він визнає, що незначні відмінності є несуттєвими. Важливо домовитися і зрозуміти основні принципи. Підтримка послідовного стилю не переслідується, оскільки l'art pour l'art. Це не дозволяє нетворчим азотистам дратувати та відволікати інших людей. Йдеться про полегшення спілкування за допомогою коду в команді.

Документ, що часто оновлюється та добре пишеться з кодовими стандартами, може бути дуже корисним, але зазвичай це не так. Документ про стандарти не відображає фактичних стандартів кодування, які використовує компанія, оскільки створити хороший документ про стандарти дуже важко і ще складніше його оновлювати.

Замість того, щоб мати поганий та оманливий документ щодо стандартів кодування, краще його не мати, а сам код представляє ці стандарти. Так чи інакше, найважливіша частина - це застосувати стандарти в коді, і для цього потрібно набагато більше, ніж просто документ. Мотивація, процеси, тренінги, інструменти тощо набагато важливіші.

Дуже важлива річ, яка недостатньо чітко сказана, - це те, що стандарти кодування - це мова: вони розвиваються. Письмовий стандарт кодування перешкоджає цьому, і якщо це не так, він постійно застаріває і марний.

Відсутність прибитого стандарту кодування вниз не так вже й погано. Якщо ви робите експертні огляди при реєстрації, коли що-небудь, що не відповідає стандарту кодування, потрапляє у сховище, це означає, що 2 людини задумалися над цим * і вирішили, що користь від цієї зміни перевищує невідповідність решті коду.

Якщо не встановлений стандарт, також видаляється бюрократизація, яка б заважала колективу компанії спробувати нову варіацію стандарту кодування для нового проекту, або тому, що вони хочуть щось випробувати, або, можливо, тому, що інший стандарт має практичні програми на деяких автоматизованих інструментах, якими вони користуються.

Списання стандарту має тенденцію до витримки більшої гнучкості, ніж спочатку передбачалося, а також займає зовсім небагато часу, який можна витратити на інші речі. Я не кажу, що ніколи не слід записувати стандарти кодування, письмові стандарти, безумовно, мають свої переваги, особливо якщо команди, що працюють в різних місцях, працюють на одній базі коду.

Сильно пов'язане: Еволюція в стандартах кодування, як ви з ними справляєтеся?

* Якщо люди не замислюються під час перевірки коду під час реєстрації, ваші проблеми набагато більше, ніж просто стандарти кодування.

Зміна їх стає головною перешкодою, і люди будуть безпечно дотримуватися букви закону, а не займатися мізками та робити все правильно.

Настане день, коли частина стандарту не буде корисною, а код погіршиться. Деякі люди дотримуватимуться стандарту, тому що це записано і вони безпечні, і тому, що там потрібно дотримуватися правил. Люди, які хочуть написати гарний код, а не стандартний код, будуть розчаровані і розлючені. Будуть аргументи та розбіжності, тоді як якби стандарт не був записаний, було б вивчення та обговорення.

Я думаю, що багато публікацій тут плутають стандарт кодування з посібником зі стилів .

Переконайтесь, що модулі, розроблені різними командами, мають однакові параметри компілятора, а ABI - це різна річ від кількості пробілів.

Такі речі, як правильний спосіб структурування файлів #include, а не забруднення глобального простору імен у файлі заголовка, повинні бути задокументовані, щоб вони могли використовуватися як контрольний список під час початкового огляду кодування та коду.

Зокрема , «не використовувати XXX , оскільки він викликає проблеми сумісності з YYY» не те , що ви б побачити, наприклад , в наступних інший код, так як він НЕ існує. Тож нехай код є таким, яким стандарти захоплені можуть бути незрозумілими або зовсім відсутні для деяких видів стандартів, і, отже, це не може бути універсальним планом.

Щось серйозно поширене і важливе, як, наприклад, не використовувати винятки чи не використовувати newв певних вбудованих системах, не може бути просто залишене загальним знанням культури, оскільки "інформація є культурною (лише)" суперечить фундаментальним принципам виробничих стандартів, таких як ISO-9000, що розробник цих вбудованих систем використовує (наприклад, для автомобільних додатків). Ці важливі речі повинні бути задокументовані, підписані та оформлені поданими формально.

Але це стосується кодування , а не стилю .

Винахідники C і C ++ показують, наприклад, використання малих імен, а не CaMelCaSe. То чому так багато розробників не наслідують прихований приклад із основи? Чи не повинен стиль стандартної бібліотеки та канонічні навчальні матеріали бути непримітним стилем, який слід дотримуватися?

Тим часом, люди роблять наслідувати приклад стандартної бібліотеки заголовків для речей , які не повинні бути скопійовані, як використання __Uglyімен для макро параметрів і включати файл без повтору малюнка.

Тож наявність матеріалів часто не сприймається як важливий стиль, або, навпаки, мати приклади, можливо, не зрозуміло, чого не слід дотримуватися в коді проекту. Обидва є контрприкладами до тези про те, що «стиль» (або конвенції кодування) найкраще залишати неявними.