Як зробити більшу кодову базу легше зрозуміти

Припустимо, я розробляю відносно великий проект. Я вже задокументував усі мої класи та функції з Doxygen, однак у мене виникла ідея помістити "примітки програміста" у кожен файл вихідного коду.

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

Наприклад:

/*
 * PROGRAMMER'S NOTES:
 *
 * As stated in the documentation, the GamepadManager class 
 * reads joystick joystick input using SDL and 'parses' SDL events to
 * Qt signals.
 *
 * Most of the code here is about goofing around the joystick mappings.
 * We want to avoid having different joystick behaviours between
 * operating systems to have a more integrated user experience, since
 * we don't want team members to have a bad surprise while
 * driving their robots with different laptops.
 *
 * Unfortunately, we cannot use SDL's GamepadAPI because the robots
 * are interested in getting the button/axes numbers, not the "A" or
 * "X" button.
 *
 * To get around this issue, we created a INI file for the most common 
 * controllers that maps each joystick button/axis to the "standard" 
 * buttons and axes used by most teams. 
 *
 * We choose to use INI files because we can safely use QSettings
 * to read its values and we don't have to worry about having to use
 * third-party tools to read other formats.
 */

Чи це буде хорошим способом полегшити масштабний проект, щоб нові програмісти / учасники проекту зрозуміли, як це працює? Окрім підтримки послідовного стилю кодування та «стандартної» організації каталогів, чи існують якісь «стандарти» чи рекомендації щодо цих випадків?

Це круто. Хочеться, щоб більше розробників програмного забезпечення зайняло час і сили для цього. Це:

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

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

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

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

Примітки вашого програміста також надають підґрунтя щодо дизайнерських рішень. Хоча це може бути цінною інформацією, я б відокремив її від заяви про відповідальність (щоб читач міг вибрати, чи хоче він читати про відповідальність класу чи його обґрунтування проекту), і перемістив би його якнайближче до джерела, яке він описує можливо, щоб максимально збільшити шанс оновлення документації, коли код є (документація корисна лише тоді, коли ми можемо довіряти її точності - застаріла документація може бути гіршою, ніж жодна!).

Враховуючи це, документація повинна залишатися СУХОЮ, тобто не повторювати інформацію, яка могла бути виражена в коді або вже описана в іншому місці (фрази типу "як зазначено в документації" є попереджувальним знаком). Зокрема, майбутні фахівці, які займаються технічним обслуговуванням, будуть просто знаннями мови програмування проекту, оскільки вони англійською; Якщо перефразовувати реалізацію в коментарях (що я бачу взагалі занадто часто, коли люди пишаються своєю документацією), це не приносить користі, і, ймовірно, буде відрізнятися від впровадження, зокрема, якщо документація не знаходиться в коді, який вона описує.

Нарешті, структура документації повинна бути стандартизована в рамках проекту, щоб кожен міг її знайти (це королівський безлад документів Петра в трекері помилок, Сью у вікі, Алан у readme та Джона у вихідному коді ...) .

Я б не погодився, що це дуже хороший підхід, головним чином через

1. Коли ви рефакторируете проект, пересувайте методи, документація порушується.

2. Якщо документація не буде оновлена ​​належним чином, це призведе до більше плутанини, ніж допоможе зрозуміти код.

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

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

Я особисто прихильник дизайнерського документа високого рівня - бажано його написати перед будь-яким кодом - який дає огляд дизайну та перелік класів та ресурсів. Дизайн зверху вниз значно спрощує речі - вашим може бути "ігровий двигун -> обладнання -> контролери -> джойстик"; таким чином, новий програміст сказав "зафіксувати кнопку" a "на контролері" xyz ", принаймні, знатиме, з чого почати шукати.

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

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

Речі, які слід включити в проектний документ:

• Архітектура додатків
• Структура логічного коду
• Потоки даних
• Основні використовувані зразки та мотивація їх використання
• Структура джерела коду
• Як його побудувати (це пропонує розуміння неявних залежностей та фізичної структури джерела коду)

Виходячи з цього, документація для класів, а також функцій / методів повинна бути заповнена відповідно . Зокрема, громадський API; повинно бути зрозуміло, що таке наступне у кожному випадку;

• Передумови
• Ефекти
• Інваріанти
• Умови виключення (кидки)

Найважливіше правило, яке я знайшов для полегшення для нових розробників розуміння кодової бази, це ідеальне узгодження.

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

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

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

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

Ще одне рішення: зменшити кодову базу. Чим менше коду там, тим простіше його зрозуміти. Refactor з невикористаного або дублюється коду. Використовуйте методи декларативного програмування . Це, звичайно, вимагає зусиль, і часто це неможливо чи практично. Але це гідна мета. Як писав Джефф Етвуд: Найкращий код - це взагалі немає коду

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

Наприклад, ігровий двигун, як правило, досить складний, і важко вирішити, що викликає, що після ста шарів абстракції. Можливо, варто створити файл на зразок "Architecture.txt", щоб пояснити, як і чому такий код структурований, і чому там існує безглуздий дивлячий шар абстракції.

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

Іноді ви можете отримати цю інформацію з нотаток менеджера проекту, але це все, що ви отримаєте, оскільки вони рідко перепишуть свої нотатки у цьому форматі.