Методика документування наявної кодової бази

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

Моє питання таким чином:

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

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

Документування базових кодів

Я настійно рекомендую дотримуватися правила розвідки зі застарілими кодовими базами. Спроба документувати спадковий проект незалежно від роботи над ним просто ніколи не відбудеться.

Внутрішньо-кодова документація

Найголовніше - використовувати засоби документації у обраному вами середовищі розробки, так що це означає pydoc для python, javadoc в java або xml коментарі в C #. Це полегшує запис документації одночасно з написанням коду.

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

Тести як документація

Ще одним важливим аспектом є хороша інтеграція та одиничні тести.

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

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

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

Документація вищого рівня

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

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

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

Хитрі питання. В основному, я б застосував метод "рефакторингу", який я б повторно зазначив як "якщо ти торкнешся коду, документуй його".

Але якщо бути точним; як виникають проблеми, і як ви повинні ознайомитись з кодом, щоб виправити помилки, які виникають, я б сказав, що ви повинні використовувати це знайомство, щоб писати коментарі, зокрема, до цього коду; по суті, мотивація виправити помилку в цей момент змусила вас отримати достатнє ознайомлення з кодом, щоб мати можливість документувати його. І з цієї причини мені б хотілося слідкувати за спорідненими гілками АБО документування непов'язаних функцій, тому що в той момент, якщо ви не виконуєте активного тестування коду (щоб перевірити свою помилку), то важко бути повністю певне, що ви точно розумієте, що робить код і чому. (Я не переживаю питання, що також може бути важко зрозуміти, що і чому код робить те, що робить, навіть під час тестування виправлення помилок; ви '

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

Одне також помічає; у вас повинна бути хороша зовнішня документація. Ви говорите, що ваш код не має посилань на зовнішню документацію; Я сподіваюся заради вас, що така зовнішня документація існує. Якщо ні, то я б фактично зробив написання цієї зовнішньої документації першочерговим завданням; Щось на рівні функціональних специфікацій, я думаю, є абсолютно критичним для всіх великих програмних проектів. Причина полягає в тому, що функціональні характеристики або документація на високому рівні цієї форми можуть допомогти запобігти "повзання функцій" або "дрейф функції" в будь-якому програмному забезпеченні; і переміщення функції (зокрема) може бути руйнівним для документації, оскільки може призвести до застарілості документації. (Я визначаю повзучість функції як прогресивне (і дратівливе) додавання функцій до програмного забезпечення; дрейф функціїз іншого боку, це те, коли набір дій, які програмне забезпечення здійснює, повільно змінюється з часом. Повзучість функції - ДОПОМОГА, тобто зазвичай передбачає збільшення набору функціональних можливостей програмного забезпечення; дрейф функції, з іншого боку, дорівнює нулю; один за одним, один фрагмент крайової функціональності визначається, щоб зробити щось інше, поки програмне забезпечення не зробить щось зовсім інше, ніж спочатку передбачалося. Перенесення функцій рідкісне, але СРОК для документації.)

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

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

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

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

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

Я б використовував коментарі Doxygen. У Doxygen є більше вихідних форматів, що у більшості інших вільних форматів, і їх легко вивчити.

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

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

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

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