Что не так с документированием кода?
Я искренне верю, что документация - ценный артефакт разработки, и бла-бла-бла.
Да, документация важна, но черт побери, пока нет ни одного способа сделать это хорошо, потому что процесс документирования сломан. Трижды. Именно так.
Вилы первые.
Обычно нам предлагают какую-нибудь фигню, которая “аффтоматизерует” процесс документирования кода, ну типа JavaDoc & co. Вы типа добавляете в код 5% текста, а волшебный ящик делает 95% черной работы и вуаля, у вас красивая документация!
Ага, похоже что в головах маркетологов именно так и происходит, ну так они же и не пишут код.
Потому что на самом деле это гнусное кидалово. Нет, вы не получаете эдакого технического писателя из коробки, все что вы получаете - еще один кусок кода, который пытается преобразовать ваш собственный код. Обычно не очень успешно.
Это не смотря на то, что вам приходится выучивать дебильный синтаксис и долбить по клавиатуре всякий раз, когда вы натыкаетесь на очередные вилы от разработчика “автоматизатора”:
- нет, не может быть больше одного примера
- нет, нельзя скрыть это
- нет, нельзя показать то
- да, вы обязаны писать именно так
- и т.д. и т.п.
Черт побери, нафига мне эта ублюдочная прилада с характером светской львицы и интеллектом клинического имбецила?
Я знаю html (он ужасен), я знаю jade (это откровение), я могу сделать что-то красивое с TwitterBootstrap (я бездарь в дизайне) , а если мне его не хватит - могу дополнить чем угодно. Да, вот это должно быть красным, а это - новый параграф, а тут нужна картинка, а здесь - листинг кода и его результат. Все должно быть как я сказал, и именно так, никакой самодеятельности. Какого хрена я должен спорить с кодом?
Резюме: не бесите меня, я лучше знаю что я имею ввиду.
Вилы вторые.
Есть стойкое мнение, что документация должна быть “вшита” в код, в таком случае программист, правя код, поправит и документацию. И все будут счастливы.
Ага, похоже что в головах менеджеров именно так и происходит, ну так они же и не пишут код.
Послушайте, они не правы, причем дважды.
Если я не хочу править документацию прямо сейчас, особенно пока я занят кодом и тестами, я не буду этого делать, даже если документация будут вставляться между операторам. Я, черт побери, занят, не отвлекайте меня. Нет, я не говорю, что написание документации - работа кого угодно, но только не программиста. Это вполне моя работа, но (и это важное “но”) в другой роли.
Роли, блин, роли, вас же учат на ваших этих MBA, что это такое. Так вот, когда пишется код - я злобный мистер Хайд, а в момент написания документации я должен быть милым доктором Джекилом. И переход от одного образа к другому требует времени и сил.
”- Но а как же актуальность документации!!?”
Ах, я воткну туда тег #TODO Update doc и займусь этим позднее.
Резюме: не отвлекайте меня, или ничего не будет готово.
Вилы вторые вторые.
Еще одна проблема с документацией, о которой почему-то нечасто вспоминают - это то, что есть (как минимум) два вида документации. Инструкция пользователя и инструкция для сервисного инженера. Каждая из них важна, но по-своему и для разных людей.
Для кода инструкция сервисного инженера (программиста) - это комментарии в коде типа “потому что” и спеки (тесты, если вас угодно). Тесты совершенно однозначно описывают как именно это работает, я всегда лезу в тесты если мне что-то непонятно по API.
Комментарии типа “потому что” экономят массу времени и сил при разборе кода-сырца:
- почему тут обратный индекс? # обратный индекс быстрее, см бенчи
- почему тут пушится запятая? # тупой API объекта требует запятую в конце
Это бесценно. Если я делаю что-то странное в своем коде - я пишу почему это случилось. В том числе и для того, чтобы рефакторя код, понять, что я ступил и это не проблема, что тут все можно поправить.
Это - те комментарии, которые должны быть в коде. Они короткие, вставлены только по делу и составляют с кодом единое целое. Я пишу их для себя. Так как я хочу, так как мне нужно.
Инструкция пользователя - совсем другое дело. Они только мешаются, захламляя место на экране и раздувая исходный код в 2-3 раза. Им тут не место. Да, именно так!
Ну, послушаете, сначала мы разбиваем все на модули, классы, методы, уменьшаем их до предела, а потом ффигачиваем к каждому 4-х строчному методу шапку из 2-х экранов доков, с описанием типа переменных, возвращаемого значения и примерами с комментариями. Это совершенно неправильно. Нелогично и отвратительно смотрится.
Пусть этот монстр живет где-то еще. В отдельной папке, в другой форме и виде. Пусть методы там будут перечислены в другом порядке, пусть будут исполняемые примеры, пространные описания профита и даже заметки. Пусть их, только не в коде.
”- Но а как же актуальность документации!!?”
Да легко, достаточно простого инструмента, который проверит что все public-методы имеют свою половинку в пользовательской документации. Элементарный матчинг имени метода класса и имени хеш-тега в файле документации. Кстати, добавляете сюда парсинг кода на наши #TODO теги и готово! Я уже подумываю сбацать такое для CoffeeScript.
”- А что если документация все-же стала неактуальна!!??”
Git расскажет вам, что за редиска правила файл класса и не пофиксила доки. Дальше сами.
Резюме: принцип “разделяй и властвуй” более универсален, чем вам казалось, позвольте мне использовать его чаще.
Итог.
Давайте подойдем к проблеме с правильной стороны и подходящими инструментами, тогда ее решение станет тривиальным, предсказуемым и управляемым.
PS. Я не отказываюсь работать, я отказываюсь заниматься фигней.
Гайд по инсталяции Mac OS X Lion 10.7.4 на Acer TravelMate 4230.
