Як зробити документацію для коду і чому програмне забезпечення (часто) погано документоване?

Є кілька хороших прикладів добре задокументованого коду, наприклад, java api. Але багато коду в публічних проектах, таких як git та внутрішні проекти компаній, є погано задокументованими та не дуже привітними для новачків.

У всіх моїх розробках програмного забезпечення мені довелося стикатися з погано задокументованим кодом. Я помітив наступні речі -

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

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

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

1. Лінь.
2. Розробники не люблять нічого робити, крім коду.
3. Безпека роботи. (Якщо ніхто не може легко зрозуміти ваш код, то його ви не можете легко замінити.)
4. Складні терміни залишають мало часу для документування.

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

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

Чи є спосіб покінчити чи полегшити це безумство? Можливо, "розробка документообігу"?

Як документувати код?

У вас уже є підказка: подивіться, як документується Java API.

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

Чому багато проектів з відкритим кодом недостатньо задокументовано?

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

Чому багато проектів із закритим кодом не документально підтверджені?

Тому що це коштує величезних грошей, щоб (1) написати гарну документацію і (2) підтримувати її.

1. Безпосередня вартість (вартість написання документації) чітко видно для зацікавлених сторін: якщо ваша команда просить витратити наступні два місяці на документування проекту, потрібно заплатити два додаткові місяці зарплати.

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

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

Я часто спостерігаю:

1. На початку команда готова багато документувати.

2. З часом тиск строків та відсутність інтересу ускладнюють ведення документації.

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

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

   • Якщо керівництво надає на це кілька тижнів, цикл повторюється.

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

Документування має бути безперервним процесом, як і тестування. Проведіть тиждень, просто кодуючи кілька тисяч LOC, і повернутися до тестів і документації дуже і дуже болісно.

Як заохотити команду писати документацію?

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

• Подавати приклад. Якщо ви пишете гарну документацію, ваші пари теж можуть почати це робити.

• Проводьте систематичні огляди коду, включаючи офіційні огляди коду, спрямовані на перевірку документації.

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

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

• Використовуйте гаміфікацію. Це поєднується з попереднім пунктом.

• Використовуйте позитивне / негативне підкріплення .

• (Див . Коментар SJuan76 ) Трактуйте відсутність коментарів як помилки. Наприклад, у Visual Studio можна перевірити опцію для створення XML-документації. Якщо ви також перевірите, чи всі попередження трактуються як помилки, відсутність коментаря у верхній частині класу чи методу зупинить компіляцію.

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

    /// <summary>
    /// Gets or sets the PrimaryHandling.
    /// </summary>
    public Workflow PrimaryHandling { get; set; }

які були, гм ..., не особливо корисні.

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

Чи є якісь хороші приклади, коли мінімальна документація не потрібна?

Документація, що пояснює архітектуру та дизайн , не потрібна:

• Для прототипу

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

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

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

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

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

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

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

тл; д-р

Якщо ви просите, щоб кожен проект був добре задокументований, то ви занадто багато просите.