Я ненавиджу більшість стандартних документів, оскільки вони, як правило, намагаються потіти дрібні речі і ігнорувати більшу картину.
Наприклад, майже всі вони скажуть, як називати змінні чи розміщувати дужки. Це чистий стиль і мало що допомагає групі кодів розробників правильно. Вони ігнорують такі речі, як структура каталогу та макет коду. Я бачив стандартні документи, в яких точно було сказано, скільки пробілів потрібно розмістити між операторами та скільки порожніх рядків між методами. Все це зазвичай закінчується топовою винятком з правила, яке просто показує, наскільки вони безглузді, і тоді вони такі великі, що за ними ніхто не може піти, що знову ж таки знущається над тим, що вони намагаються зробити. .
Тепер для мене я використовую багато різних програмних програм у багатьох різних програм, і всі вони мають різні стилі. Я просто звикаю до цього, не скаржуюся, що не існує спільного стилю для всіх груп розвитку. Поки код є загальним стилем усього проекту, мені дійсно все одно, що це за стиль. Тому моє перше правило для всіх стандартних документів таке: Дотримуйтесь послідовного стилю кодування в рамках проекту . ніхто не повинен давати інжир, де є дужки, якщо вони однакові. Візьміть релігійні війни і засуньте їх :)
Друге - це компонування коду. Коли я підбираю фрагмент коду, я хочу побачити, що його викладено за аналогічними лініями, як і інші, подібні твори. Якщо у мене є веб-служба, я хочу, щоб назва договору wsdl було зрозумілим, я хочу, щоб ім'я реалізації було зрозумілим. Я не хочу, щоб хтось придумав абсолютно новий і інший макет для файлів і класів. Це означає, що я повинен грати "полювати на код", що викликає неприємності. Якщо це виглядає так само, як і останній проект, над яким я працював, я можу відразу знати, де знайти те, що шукаю, і це, мабуть, найбільша допомога в роботі з кодом інших людей, який я знаю. Отже, збережіть структуру того, як викладений код (наприклад, папка Документація для документів, інтерфейси для інтерфейсів тощо - все, що це працює для вас, але дотримуйтесь його).
Артефакти коду також повинні бути присутніми, тому вам потрібно сказати, чи очікувана обробка помилок є винятками або кодами помилок - тобто. функціональна архітектура документа, яка використовується . Слід також сказати, який тип журналу використовувати та як представити користувачеві журнали / помилки або будь-яку підсистему, яка використовується для управління кодом у дикій природі. Я працював у тому місці, де кожен проект робив журнал по-різному - було жалко, як кожен випуск коду повинен мати свій, різний, операційний документ, який розповідає хлопцям-операторам, як сказати, чи пішов він не так. Тут є дійсними журнал подій, файл журналу (у такому випадку де) та ін. Це ж стосується і інших поширених аспектів коду - як його налаштувати (немає сенсу використовувати файл .config для деяких програм, або користувацьку БД, або параметри командного рядка, або реєстр для інших).
Коротше кажучи, єдине, що має значення, - це послідовність . Оскільки величезні документи стандартів занадто багато для читання та запам'ятовування, я вважаю за краще просто повідомити людям про речі, які вони не бачать (наприклад, архітектурні стандарти, такі як ведення журналів), і сказати їм, щоб вони писали код, який вони пишуть, відповідно до того, що там є. А якщо у вас вже немає коду, тоді вам не потрібен стандартний документ! (ну, поки ви не написали достатньо, щоб зробити його корисним).
Тож візьміть із цього основні моменти: не намагайтеся скласти юридичний документ , подумайте про речі, які не є кодуючими, а також про те, як працює код і як код відповідає очікуванням інших людей. Тоді довіряйте людям робити добрий код, і ви побачите, що вони роблять. (а якщо їх немає, ви можете мати слова з ними, не потрібно складати це як закон).