Миф о документации
Программист, заступая на новую работу, каждый раз искренне изумляется и негодует, что "система не документирована". Это негодование - по соей силе бледное подобие негодования второго рода, которое тот же программист испытывает, если ему предложить описать простым человеческим языком, что он недавно наколбасил. И не забывать регулярно обновлять
( Read more... )
Во-первых, что нужно писать в документации -
перечисляю по убыванию важности.
1. Зачем и почему написан этот модуль (эта программа),
опционально - кто и когда попросил его написать.
2. Какие задачи должен решать модуль (программа).
3. Форматы входных и выходных данных, конфигов.
Во-вторых, что не нужно писать в документации.
Не надо описывать, что делает каждая функция/метод,
за исключением хитроумных алгоритмов, где стоит указать
название (или несколько названий) и 2-3 ссылки
на книжки и/или сетевые ресурсы.
В-третьих, о мотивации для писания документации.
Вот вы управляете программистами, верно?
Сколько раз Вы хвалили человека, - нет, не деньгами хвалили,
а именно произносили слова признательности и одобрения
за то, что человек хорошо что-то задокументировал?
Не хочу заочно обвинять, но подозреваю, что мало хвалили.
А ведь доброе слово и кошке приятно.
Вот если человек замыканий с коллбэками понавставляет
заковыристых - это да,
это вызовет одобрение коллег и программирующего начальства.
А тот, кто пишет документацию, - он козёл:
открываешь исходники, а там чёрным по белому написано
зачем сделан этот модуль и какие задачи он должен решать.
После этого чужой код читается влёт.
А что мы думаем о человеке, чей код легко читать?
Это козёл.
Потому что код настоящего интеллектуала читать должно быть трудно.
Т.е. возникает перверсия - если код читать трудно,
значит это подлинный, глубинный интеллектуал.
Ах, тебе не нравится код за Антоном сопровождать?
Непонятно? незадокументировано?
Ну так это значит, что Антон умён, а ты глуп.
Ах, за тобой код легко сопровождать, ты описываешь постановку вопроса?
Значит, ты глуп.
Риспект и уважуха в коллективе - тому, кто не пишет документацию.
Ну, и кем после этого приятней быть - упёртым козлом или интеллектуалом?
Вернусь к вопросу о похвале.
А за что человека хвалить-то? - ведь документация не приносит денег.
Документация для пользователя, которому продают продукт,
ещё как-то оправдывает себя в глазах менеджмента.
А вот внутрення документация (программист-программисту) на систему
абсолютно бессмысленна с точки зрения ROI с точки зрения менеджера.
А на самом деле сколько часов, скольо куража потеряно
из-за того, что внутренней документации на продукт нету?
Это трудно считать, для этого трудно составить метрику,
но это не значит, что потерь нет.
Раз уж заговоил о мотивации, то вот что:
отсутствие документации - это власть программиста над кодом,
а через код, - власть над коллегами и влияние на начальство.
Идут, идут коллеги к Ивану, кланяются в ножки и спрашивают:
что-то ты Иванушка изволил придумать здесь, понамыслить такого?
Начальство смотрит и делает вывод:
ай да умён Иванушко, сидит кум-королю,
а ему все в ножки кланяются - дурачки-то,
которые за Иваном его гениальный код сопровождают.
А Ивана - уже на новый участок переброслили, новый код плодить.
Растёт Иван.
Внимание, вопрос: когда программист делает свой код
непонятным, в том числе и недокументированным?
Внимание, ответ - вот один из типичных случаев.
Программист полубессознательно делает свой код
непонятным и недокументированным тогда,
когда начальство устраивает в коллективе крысиные бега,
стравливает людей, и люди инстинктивно защищаются,
шлют окружающим мессэдж:
если меня подсидят или если меня уволят,
вам придётся сопровождать мой код.
Вывод: слабая документированность ПО -
верный признак плохих человеческих отношений в коллективе.
Если на фирме люди открыты и работают без подлянок и подсидок,
то они гораздо охотнее документируют свой код,
потому что мало никому не нравится жить в состоянии войны,
а большинству нравится жить в состоянии сотрудничества.
Т.е. если начальство хочет получить ненулевую
документированность системы, то надо начинать
с выстраивания здоровых отношений в коллективе.
Reply
Reply
Reply
Я прошу вас перенести все эти комментарии в свой журнал.
Reply
Reply
Reply
Ну а вообще-то у нас веса разные, конечно, вы сформировали качественную читательскую аудиторию, поэтому вставить длинный коммент в ваш жж для меня эффективнее, чем делать полноценные записи в моём в ЖЖ.
Вас понял, в вашем журнале я постараюсь писать покороче.
Reply
Когда так получается, это всегда верный признак, что вам надо сделать свой собственный пост-статью, и ссылаться на него в дискуссии в комментах. Отличный повод написать пост - почему не написать? Это повышает ценность вашего журнала, в первую очередь.
И второе - я никого не баню просто так. В бан отправляются люди, предпочитающие обсуждать личность собеседника, а не предмет дискуссии. Там даже у меня правила где-то были в ленте. Утонули.
Reply
Leave a comment