Як привчити розробників документувати свій код
Код погано документовано? Цілком ймовірно, що проблема не в програмістах, а в тому, як побудовано роботу в компанії.
Досить складно знайти та залучити до своєї команди висококласних розробників. А от придбання таких співробітників, які вміють добре документувати код, — це, на перший погляд, не проблема.
Давайте поки що абстрагуємося від документації користувача. Мануали, довідкові посібники та онлайнова документація — це тексти, створення яких краще залишити технічним письменникам. Адже спеціалізація техписів – викладати доступною мовою технічні специфікації. Така документація пишеться вже готового продукту. Однак у процесі розробки програми важливо вести докладну документацію для внутрішнього використання.
Чому програмісти не документують код, скільки документації потрібно та як краще її робити
У команді розробників завжди є плинність — у бізнесі це нормально. Програміст може змінити роботу, перейти з одного відділу в інший або взагалі піти з сфери. Не виключені й зовсім похмурі обороти – тяжка хвороба, інвалідність чи смерть. Всі ці фактори можуть різко обмежити можливості команди в невідповідний момент. Код також старіє; програміст цілком може забути, як працює його власний код, якщо не займався ним протягом року чи довше.
Чому програмісти не пишуть документації?
Існує багато причин, через які розробники не документують свій код. Деякі з них простіше усунути, ніж інші.
Таке ставлення до роботи руйнівне та неприйнятне. Але приклади такого непрофесіоналізму зустрічаються рідше, ніж може здатися. В абсолютній більшості випадків розробникине документують код з набагато більш прозових причин.
По-перше, коли саме програміст має документувати код? Загальновідомо, що програмні модулі часто пишуться, а потім багаторазово переписуються перед релізом, але можуть дописуватись і пізніше. Якщо розробник занадто рано почне документувати реалізації API, він ніби підписується під проектними рішеннями, які є лише гіпотетичними. Більше того, якщо пізніше специфікація чи вимоги зміняться, але ніхто не згадає, що й мануал потрібно переписати, то виникне неточна та застаріла документація. Такий результат ще гірший, ніж повна її відсутність. Ці проблеми лише ускладнюються в контексті сучасних методологій «гнучкого» програмування, де наголошується на надшвидке створення готового коду та ітеративну розробку.
Ще одне питання – скільки часу програміст має витрачати на написання документації? У більшості компаній основні обов'язки розробника полягають у проектуванні, реалізації, налагодженні та підтримці коду. Але якщо результативність програміста оцінюється насамперед щодо виконання цих основних завдань, він, швидше за все, займатиметься рештою (менш істотною) роботою в останню чергу, особливо якщо в організації надто багато уваги приділяється нормам продуктивності, які беруться зі стелі. Швидше за все, документування коду сприйматиметься як «несуттєва робота».
Скільки потрібно документації?
Крім того, традиційні різновиди докладної документації для розробників втрачають популярність, особливо в тих організаціях, де практикується гнучка розробка. Загальновідомо, що підрахунок рядків коду є поганим способом вимірювання продуктивності програміста. Аналогічно кількість рядків чи сторінокпідготовленої документації не завжди корелює із її цінністю.
В даному випадку діє лише одне залізне правило: розробники повинні писати «хорошу» документацію. І все. Якщо документація досить якісна для виконання поставлених завдань, то вона хороша. Будь-який додатковий текст, ймовірно, буде зайвим. Звісно, звучить розпливчасто, але тут справді складно сформулювати якісь правила; розробники повинні самі вміти визначати, яка документація хороша.
Прийоми покращення документації
На розвиток культури написання документації потрібен час. Підтримка цієї культури потребує постійного стимулювання. Менеджер повинен користуватися скоріше пряником, ніж батогом. Програмісти — звичайнісінькі люди, вони віддають перевагу стимулам, а не наказам. Звичайна похвала дозволяє досягти багато чого, але менеджери можуть винаходити й інші способи винагороди розробників. Вам трапляється іноді викликати програміста і навантажувати його підтримкою програми на вихідні або розгортанням оновлень серед ночі? Якщо програміст не полінуеться ще й написати документацію — дайте йому заслужений перепочинок. Зрозуміло, фінансові стимули працюють не гірше.
Вже багато років у різних методологіях програмування розвиваються ідеї у тому, що документація коду має стати природнішою і автоматичної. Найбільш яскравим проявом такого підходу є концепція «грамотного програмування», запропонована Дональдом Кнутом. Відповідно до цієї теорії, синтаксис алгоритмів має наближатися до синтаксису природної людської мови. Більш практичним підходом, який застосовується в багатьох організаціях, є «самодокументування коду». У цьому випадку програмісти повинні дотримуватись певних стандартів іменування.та структурування коду. В результаті код стає більш однорідним та легким для сприйняття.
Проте найефективніший спосіб привчити розробників до документування коду – це командний підхід до написання документації. Якщо група програмістів відповідає за розробку кількох модулів коду, запропонуйте зробити презентацію для всієї команди і пояснити, як працює їх код. У процесі підготовки такої презентації вони виконають більшу частину рутинної роботи з підготовки формалізованої документації, а ті питання, які виникнуть у ході презентації, допоможуть прояснити неоднозначності, що залишилися.
Ще один зручний прийом – парне документування. Фактично тут процес документування будується за принципами гнучкої розробки. Якщо документування коду — не ізольований вид діяльності, а значна частина здійснення загальнокомандних цілей, то ця робота сприймається як менш обтяжлива і стає природною частиною повсякденної праці.
Через все вищесказане червоною ниткою проходить ще одна теза: документування коду ніколи не є пасивним процесом. Занадто поширена думка про те, що документування може відбуватися автоматично, а коли такої інформації немає — починаються скарги. На жаль, документування коду - одне з таких завдань, які не слід вирішувати заднім числом. Починайте написання документації вже сьогодні. Якщо ж налагодити таку роботу в компанії не вдається, то, швидше за все, справа не в розробниках, а в неправильно побудованих бізнес-процесах.