?

Log in

November 2016   01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
cartoon

Миф о документации

Posted on 2011.06.11 at 01:02
Tags: ,
Программист, заступая на новую работу, каждый раз искренне изумляется и негодует, что "система не документирована". Это негодование - по соей силе бледное подобие негодования второго рода, которое тот же программист испытывает, если ему предложить описать простым человеческим языком, что он недавно наколбасил. И не забывать регулярно обновлять каждый раз, когда он вносит в колбасево изменения.

Но это все проза жизни. Что _действительно_ удивительно - это то, перечисленное не мешает программисту на следующем месте работы опять искренне удивляться, что "система не документирована". Ну пиздец же, правда? :)

Терминальной стадией болезни является требование найма "документатора". Это обычно нихуя не понимающий ни в коде, ни в предметной области несчастный человек, который должен оное колбасево описывать. Извлекая информацию посредством ментального сканирования.

А у нас применяется JavaDoc/Oxygen/ПрочаяХуйня, скажете вы. А я всегда аккуратно пишу эти гребанные комментарии, языком Пушкина и Толстого, скажете вы.

А я вам, во-первых - на предмет "аккуратно" и "всегда" не поверю. :) Ну, в самом деле, говорить всякое можно, но меру-то знать надо. :)

А во-вторых - в описываемом мной явлении дело вовсе не в JavaDoc. И не в том, что надо, наступив себе на яйца, непрерывно "документировать".

Дело в другом. Если вы все понимаете, то реальность - она такая, какая есть. Что характерно - если вы не все понимаете - то она один хер такая, как есть. Она состоит в том, что "документация" - это неуловимый Джо, и на это есть вполне объективные причины. Если, конечно, речь не идет о публичном API систем, которым активно пользуются, ну, хотя-бы, десятки тысяч людей (и тогда аудитория "читателей" сравнима с тиражом книги).

Comments:


pingback_bot
pingback_bot at 2011-06-10 21:08 (UTC) (Link)

No title

User squadette referenced to your post from No title saying: [...] ь каждый раз, когда он вносит в колбасево изменения. http://gaperton.livejournal.com/60277.html [...]
vozbu
vozbu at 2011-06-10 21:09 (UTC) (Link)
Эт что за мифический программист такой? По-моему наоборот должно быть - приходишь на новую работу с мыслью "и здесь наверное никакой документации, кроме кода", а тут на тебе - все описано и регулярно обновляется. Вот это сюрприз!
Gaperton
gaperton at 2011-06-10 21:20 (UTC) (Link)
Ага. Еще если б мозг напрягать не пришлось при ее чтении, и все без усилий понятно было б - это вообще сказка была бы.

Так ведь даже в этом случае придется :) Так что это все будет плохая, негодная документация. Нехрена ж не понятно все равно.
malica_dee
malica_dee at 2011-06-10 21:40 (UTC) (Link)
Документирование каждой функции и каждого класса, кроме того самого случая публичного API, действительно нахрен никому не нужно, но я не могу сказать, что документация в принципе не нужна. На проекте нужны доки, которые описывают архитектуру, протоколы, формат конфигов и т. п. И эти доки (с тяжкими вздохами и регулярными упражнениями в употреблении обсценной лексики) таки пишутся большинством программистов.
Дмитрий Арсентьев
dmarsentev at 2011-06-11 00:24 (UTC) (Link)

документацию пишут козлы для козлов, а победители пишу

Из личного опыта.

Во-первых, что нужно писать в документации -
перечисляю по убыванию важности.
1. Зачем и почему написан этот модуль (эта программа),
опционально - кто и когда попросил его написать.
2. Какие задачи должен решать модуль (программа).
3. Форматы входных и выходных данных, конфигов.

Во-вторых, что не нужно писать в документации.
Не надо описывать, что делает каждая функция/метод,
за исключением хитроумных алгоритмов, где стоит указать
название (или несколько названий) и 2-3 ссылки
на книжки и/или сетевые ресурсы.

В-третьих, о мотивации для писания документации.
Вот вы управляете программистами, верно?
Сколько раз Вы хвалили человека, - нет, не деньгами хвалили,
а именно произносили слова признательности и одобрения
за то, что человек хорошо что-то задокументировал?
Не хочу заочно обвинять, но подозреваю, что мало хвалили.
А ведь доброе слово и кошке приятно.
Вот если человек замыканий с коллбэками понавставляет
заковыристых - это да,
это вызовет одобрение коллег и программирующего начальства.
А тот, кто пишет документацию, - он козёл:
открываешь исходники, а там чёрным по белому написано
зачем сделан этот модуль и какие задачи он должен решать.
После этого чужой код читается влёт.
А что мы думаем о человеке, чей код легко читать?
Это козёл.
Потому что код настоящего интеллектуала читать должно быть трудно.
Т.е. возникает перверсия - если код читать трудно,
значит это подлинный, глубинный интеллектуал.
Ах, тебе не нравится код за Антоном сопровождать?
Непонятно? незадокументировано?
Ну так это значит, что Антон умён, а ты глуп.
Ах, за тобой код легко сопровождать, ты описываешь постановку вопроса?
Значит, ты глуп.
Риспект и уважуха в коллективе - тому, кто не пишет документацию.
Ну, и кем после этого приятней быть - упёртым козлом или интеллектуалом?

Вернусь к вопросу о похвале.
А за что человека хвалить-то? - ведь документация не приносит денег.
Документация для пользователя, которому продают продукт,
ещё как-то оправдывает себя в глазах менеджмента.
А вот внутрення документация (программист-программисту) на систему
абсолютно бессмысленна с точки зрения ROI с точки зрения менеджера.
А на самом деле сколько часов, скольо куража потеряно
из-за того, что внутренней документации на продукт нету?
Это трудно считать, для этого трудно составить метрику,
но это не значит, что потерь нет.

Раз уж заговоил о мотивации, то вот что:
отсутствие документации - это власть программиста над кодом,
а через код, - власть над коллегами и влияние на начальство.
Идут, идут коллеги к Ивану, кланяются в ножки и спрашивают:
что-то ты Иванушка изволил придумать здесь, понамыслить такого?
Начальство смотрит и делает вывод:
ай да умён Иванушко, сидит кум-королю,
а ему все в ножки кланяются - дурачки-то,
которые за Иваном его гениальный код сопровождают.
А Ивана - уже на новый участок переброслили, новый код плодить.
Растёт Иван.

Внимание, вопрос: когда программист делает свой код
непонятным, в том числе и недокументированным?
Внимание, ответ - вот один из типичных случаев.
Программист полубессознательно делает свой код
непонятным и недокументированным тогда,
когда начальство устраивает в коллективе крысиные бега,
стравливает людей, и люди инстинктивно защищаются,
шлют окружающим мессэдж:
если меня подсидят или если меня уволят,
вам придётся сопровождать мой код.
Вывод: слабая документированность ПО -
верный признак плохих человеческих отношений в коллективе.
Если на фирме люди открыты и работают без подлянок и подсидок,
то они гораздо охотнее документируют свой код,
потому что мало никому не нравится жить в состоянии войны,
а большинству нравится жить в состоянии сотрудничества.

Т.е. если начальство хочет получить ненулевую
документированность системы, то надо начинать
с выстраивания здоровых отношений в коллективе.
aamonster
aamonster at 2011-06-11 05:34 (UTC) (Link)

Re: документацию пишут козлы для козлов, а победители пи

Дмитрий Арсентьев
dmarsentev at 2011-06-11 00:25 (UTC) (Link)

не уместилось

Ну и в-четвёртых:
когда программерская документация формируется естественным образом?
Например, когда выцепляется кусок системы и отдаётся на аутсорс.
Незнакомым людям.
В чужие руки.
И они нам будут писать функции, которые мы будем вызывать?
Ой, мамочки. Срочно писать спеки!
Вот тогда программист посылает начальников подальше,
потому что начальники говорят "да это всё фигня,
да ты спихни как-нибудь, да документация - это вообще не работа".
Такого начальника программист шлёт подальше
и пишет - не только тесты, но и документацию -
весьма скрупулёзно и продуманно.

Т.е. всякие приёмо-сдаточные процедуры - они
естественным образом генерируют качественную документацию.
Alexey Fyodorov
23derevo at 2011-06-11 01:22 (UTC) (Link)

Re: не уместилось

+1 за приёмо-сдаточные процедуры. И +1 за документацию пользователя.

Если контора нанимает долбоёба, который пришет непонятный код - это её проблемы. Если менеджер не может отследить странное поведение такого разрабочика - это снова проблемы конторы. Если в конторе нету code review и непонятный никому говнокод попадает в репозиторий - это снова проблемы конторы.

Если происходит всё вместе - это не контора, а говно. Слать её нахуй.

Далее, контору, устраивающую крысиные бега, нормальному инженеру следует тоже слать нахуй, не заботясь о том, как бы в ней продержаться. Нахуй нужна такая контора.


Книга учёта жизни
balbesko at 2011-06-11 09:16 (UTC) (Link)
У нас отсутствие документации компенсируется постоянной ротацией программистов, аналитиков и тестеров, постоянным парным программированием, и редкими фотографиями бизнес моделей, накаляканых на стене.
А, и, конечно же, аксептанс тестами. Например, shouldCancelRemainingQuantityForBuyOrderIfNotEnoughLiquidity. Любое программирование начинается с написания таких вот тестов.
Alexey Fyodorov
23derevo at 2011-06-11 21:16 (UTC) (Link)
автотесты?
Кирилл Данилов
donz_ru at 2011-06-11 09:25 (UTC) (Link)
Колбасево в некоторые моменты называется релизом и документируется релиз. Как минимум архитектура, неочевидные вещи, пошаговая инструкция по сборке работающего приложения из колбасева с репозитарной версией X.
Нужная штука, короче.
Alexey Fyodorov
23derevo at 2011-06-11 21:25 (UTC) (Link)
Вы аккуратнее пишите. Вас могут читать москвичи из ru_java! Которые потом на интервью спросят вас о том, что именно вы хотели сказать этим постом)))
aka_author
aka_author at 2011-06-11 12:43 (UTC) (Link)
*** Это обычно нихуя не понимающий ни в коде, ни в предметной области несчастный человек ***

Документировать можно даже брошенный код, мы с коллегами занимались такими задачами. Другое дело, что получается довольно дорого по сравнению с документированием силами автора.
Alexey Fyodorov
23derevo at 2011-06-11 21:17 (UTC) (Link)
> мы с коллегами занимались такими задачами

помогло?
philonet
philonet at 2011-06-11 20:01 (UTC) (Link)
Замечание человека не в теме: при написании кода все равно ведь происходят обсуждения? По мылу даже или в скайпе или я не знаю как там у программеров принято. Ну вот все это и считать какой-никакой, а документацией. С одной стороны, лучше чем ничего, с другой - никому не напряжно и даже естественно.

Другой вопрос, как обсуждения в код вставлять. Но ведь это уже второстепенная ерунда, правда?
Дмитрий Арсентьев
dmarsentev at 2011-06-12 21:57 (UTC) (Link)

"документация", размазанная по переписке

Когда все ключевые решения размазаны по переписке, ага-ага.
Плавали, знаем.
По мылу, по аське, по скайпу.
И потом ищешь: кто писал? каким транспортом доставлял?
Да где-же это письмо? Ведь было же! Было!?
Или устно обсуждали по скайпу?
Natasha Vallander
nata_vallander at 2011-06-12 09:55 (UTC) (Link)
А еще у документации есть такая интересная особенность - как ни старайся, она всегда не актуальная.
Если не актуальна клиентская документация, то обычно это появляется как "на формочке новые поля" или фича не описана, а вот если не актуальна девелоперская (например в java doc) то, тут варианты могут быть сильно разные вплоть до багов с многопоточностью которые потом месяцами ловить можно.
Дмитрий Арсентьев
dmarsentev at 2011-06-12 22:11 (UTC) (Link)

а ещё нельзя учить программированию

"А еще у документации есть такая интересная особенность - как ни старайся, она всегда не актуальная."

А ещё нельзя учить программированию, а можно учить толоько истории программирования. Потому что технологии так быстро меняются, что сегодняшний передний край завтра будет историей.
Поэтому учить вообще не надо? так что ли?
Владимир Меркушев
Владимир Меркушев at 2011-06-13 06:37 (UTC) (Link)

Именно поэтому...

...идельной считается система, не требующая наличия документации.

Возьмем программу Блокнот — для нее тоже написана справка, но маловероятн, что кто-то пользовался ей - и так все ясно как день.

Если взять что-то посложнее, например одну из CMS - ее действительно можно спроектировать таким образом, чтобы справка не потребовалась - все должно быть на «своих» местах. Если какой-то пункт описан недостаточно - можно ввести разворачивающиеся комментарии или иконки «?» с всплывающей подсказкой - это одновременно и справка и нет, потому что все едино, не нужно лезть куда-то, что-то скачивать или листать.

Единственный случай, когда справка необходима как воздух, это системы разработки: программирование, черчение, сложный дизайн, 3D и т.д.
Gaperton
gaperton at 2011-06-13 09:48 (UTC) (Link)

Re: Именно поэтому...

Абсолютно правильный вывод. И - единственный в ветке.

Причем, это же касается и программного кода. Для которого проблема решается автоматической привязкой коммитов к системе учета ошибок и работ, нормальным проектированием, и раздачей осмысленных идентификаторов.
Дмитрий Арсентьев
dmarsentev at 2011-06-13 13:17 (UTC) (Link)

заголоовк не влез

Заметил, что в моём комменте заголовок не влез.

Вашу позицию переформулировал для себя так:
документацию пишут козлы для козлов,
а победители пишут код.

Может быть, я понял вас неправильно.

Думаю, ваша позиция продиктована тем,
что лично вы - сильный, топовый программист
или менеджер программистский,
пишущий системы с нуля.
А если вам попадается заказчик,
который хочет предложить вам сопровождать систему,
вы оказываетесь достаточно агрессивны и убедительны,
чтобы переубедить его переписать систему с нуля.
Именно поэтому для вас документация не нужна.
Или вы цепляетесь к унаследованной системе по её, системы, API,
и вот описание этого API вы требуете с заказчика
с присущей вам жётскостью. Тут вам в голову не приходит,
что документация не нужна.

Не все могут быть такими победоносными, как лично вы.
При сопровождении больших систем описание архитектуры
очень даже нужно.
Gaperton
gaperton at 2011-06-18 14:55 (UTC) (Link)

Re: заголоовк не влез

> Вашу позицию переформулировал для себя так:
> документацию пишут козлы для козлов,
> а победители пишут код.

Это, конечно, очень удобно - выдумать какую нибудь ерунду, а потом рассуждать, чем же продиктована такая позиция "собеседника".

Я вас прошу впредь не приписывать мне собственные мысли. Комментировать эти выдумки, я, естественно, не буду - не интересно. Пусть они останутся на вашей совести.
r_r_m at 2011-06-14 08:23 (UTC) (Link)

RFC и иже с ними

Я бы позволил себе упомянить всевозможные формальные спеки (RFC? стандарты и т.п.).
Если система реализует, что-то описываемое спеками, то эти спеки можно считать частью документации этой системы.

Пример:
SNMP - RFC описавыют все (запросы/ответы, форматы сообщений, способо конфигурировани, представление информации, идеалогию системы).

Теперь делаем все тоже самое - но своими проприетарными средствами. И либо это тоже как-то описано и можно прочитать, либо мы начинаем ползать по коду с постоянным вопросом "Это так и надо? Если да, то почему именно так? Или тут люди ошиблись просто?". И людей, ктр могут ответить уже нет рядом.
Причем некторые аспекты работы могут вылезти очень сильно потом, например юз-кейс редкий.

Так вот в этой ситуации, любая документация благо. Даже старая. Даже не соответствующая коду. По ней можно ход мыслей предыдущих поколений проследить.


Gaperton
gaperton at 2011-06-18 15:03 (UTC) (Link)

Re: RFC и иже с ними

> И либо это тоже как-то описано и можно прочитать, либо мы начинаем ползать по коду с постоянным вопросом "Это так и надо? Если да, то почему именно так? Или тут люди ошиблись просто?".

Для ответа на эти вопросы при ползании по коду уже более чем десять лет в системах контроля версий есть режим "annotate" или "blame" (в TortoiseSVN).

Для этого, правда, нужна самая малость - для начала приучить себя и других содержательные комментарии к коммитам писать, ага.

Большинство ломается уже на этом. Хотя это куда как проще, чем писать RFC в стиле IETF, но - гораздо сложнее, чем рассуждать о них в сетях.
Malckhazar
malck at 2011-06-14 09:14 (UTC) (Link)

Сумбурно-задумчиво

Вспомнилось мнение толь из МакКоннелла, толь из Фаулера, что программист должен иметь степень по литературе, чтобы писать хороший код. Следом вспомнилась книга вроде "Как читать код" или вроде того, авторства Деомидиса Спинеллиса.

Как не столь давний студент могу сказать, что в образовании погроммистов многих вещей не хватает. Умения читать код, например. Или умения проектировать, выделять сущности. Ту же документацию писать, пусть не в полном объеме, а так, хотя бы вкратце.

Ну, вот как-то так.
Alexander  Mikhalev
alexander_mikh at 2011-06-15 17:48 (UTC) (Link)
После обсуждения здесь, открыл тесты в https://github.com/nigma/pywt , там 5 строчек:
#!/usr/bin/env python

import doctest
import glob

files = glob.glob("../doc/source/regression/*.rst")

for path in files:
    print "testing %s" % path
    doctest.testfile(path)

И отсюда вопрос - это только в питоне научились обьединять документацию с тестами?
vassilsanych
vassilsanych at 2011-06-21 10:56 (UTC) (Link)

По опыту

Если код хорошо документирован (или даже передокументирован: когда комментарии после каждой строчки), то обычно сильно страдает "самодокументирование", т.е. имена классов, их свойств и методов, что в свою очередь отрицательно влияет на архитектуру. Потому что если программист не знает, как назвать метод/класс/сборку, значит это 95% неправильный метод/класс/сборка. А "документировать" много ума не надо.
Прямо сейчас вокруг меня толпа ботанов (политика фирмы), которые имеют кучу сертификаторов, "хорошо документируют", но это не мешает им плодить корявых монстров. Наверное даже способствует (документрование - корявости, академичность - монструозности).
Владимир Меркушев
Владимир Меркушев at 2011-06-21 13:01 (UTC) (Link)

Что касательно кода...

порою достаточно:
- подписывать назначение функций и классов, расписывая кратко входящие и исходящие переменные и константы
- обозначать вход и выход из цикла, описывая, что в этом цикле происходит
- стараться адекватно именовать важные переменные (думаю, это не относится к счетчику цикла, если он всего один, или к промежуточным переменным, не влияющим на систему в целом или относящимся к циклу/функции/классу). Для этого обычно применяют два подхода: подчеркивание (пример: cat_pages) или заглавные буквы (пример: MoveItFaster), что несколько медленнее (обычно не более 1-3 секунд) в плане осмысления и набора.
- соблюдать отступы (в этом помогут хорошие редакторы кода)
- оставлять пустое пространство между функциональными блоками (условное разделение) кода, чтобы «глаз отдыхал»

Есть, что добавить?
pingback_bot
pingback_bot at 2011-06-22 10:28 (UTC) (Link)

Проектная документация и Scrum

User goldtester referenced to your post from Проектная документация и Scrum saying: [...] Наткнулся на два замечательных поста про документацию: "Миф о документации" [...]
dr_hyder
dr_hyder at 2011-10-10 10:40 (UTC) (Link)
Я на разных стадиях бытия программистом был как "документация? что это?", так и "всё надо строго документировать!". Остановился на том что документация должна быть в некоторых местах, но вообще код просто должен быть написан прежде всего понятно. Если не понятен код - переписывается так чтоб стал понятен при беглом просмотре.
lokeemir
lokeemir at 2014-01-15 18:43 (UTC) (Link)
Спасибо большое за подробное описание и ответы на вопросы!
Прочитал и пост, и все обсуждения.
Я сейчас как раз изучаю вопрос ведения документации на проекте, практическую пользу от этого и возможные альтернативы.
Ваш пост серьезно повлиял на мою точку зрения, учитывая отсутствие у меня практического опыта использования подходов, а не только моих личных ощущений.

P.S. Это сразу про оба поста, включая продолжение.

Edited at 2014-01-15 06:45 pm (UTC)
Previous Entry  Next Entry