?

Log in

No account? Create an account
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.18 at 23:06

Comments:


blueher at 2011-06-19 18:13 (UTC) (Link)
Я бы добавил ещё один вид документации - "time capsule" или "письмо себе N+10-летнему" - обычно пишется не при написании кода, а при отладке, когда программист понимает что забыл как работает этот код и сам для себя (для следующей отладки) это описывает. Это не договор (пишется в основном для себя и по факту сделанного) не справочник (не поддерживается в актуальном состоянии) и не учебник (пишется для себя или человека на себя похожего). Это как правило довольно внятная документация (пишется же для себя) без "воды", охватывает только самую суть.
Gaperton
gaperton at 2011-06-19 18:17 (UTC) (Link)
Я такое обычно в комментариях к коду писал. Так оно вернее дойдет. И когда понадобится - будет находится в самом годном для этого месте. А то обидно будет, если послание в будущее отправишь, но забудешь, где почтовый ящик, и в какой момент его надо открыть, верно?

А программный код - это особый вид технической документации. Это исполняемая спецификация.
Gaperton
gaperton at 2011-06-19 18:19 (UTC) (Link)
При этом, выразительных средств, скажем, С++ - достаточно, чтобы свести комментарии к минимуму. Он удивительно выразителен и читабелен при правильном приготовлении.

Что, впрочем, касается любого современного языка.
hedgeov
hedgeov at 2011-06-19 19:43 (UTC) (Link)
Я буквально вчера натолкнулся на проблему -- описано все, кроме одного маааленького блока. И вот что в этом блоке делается -- ну ни разу не понятно, хотя сам год назад это писал. Я это к чему: иногда случается, что не угадаешь с комментариями. Что-то очевидное на момент прочтения откомментируешь, а что-то не очевидное на момент прочтения (но совершенно тривиальное на момент написания) -- нет, потому что "выразительных средств достаточно". Так что лучше соломки подстелить на максимальной площади. Как даже собственный мозг взыграет -- совершенно не известно, а чужой и подавно.
Gaperton
gaperton at 2011-06-19 20:01 (UTC) (Link)
> И вот что в этом блоке делается -- ну ни разу не понятно, хотя сам год назад это писал. Я это к чему: иногда случается, что не угадаешь с комментариями.

Комментарии тут не причем. Код надо лучше писать. Хорошему коду комментарии не нужны.

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

Нет никакого смысла писать путанно, заставляя людей много читать. Если для понимания кода нужна специальная дока - к чертям такой код.
hedgeov
hedgeov at 2011-06-19 20:25 (UTC) (Link)
Там ровно 5 строк, 2 условия и 3 присвоения. Все переменные совершенно понятные, но вот зачем они делают то, что делают -- на момент написания было очевидно, а на момент прочтения уже не очень -- пришлось потратить время. Просто при этом всё вокруг очень доходчиво и понятно, и с комментариями, и с говорящими именами -- я всегда для себя код пишу, ибо память ну оочень девичья :)
Пойнт в том, что на выразительные средства языка надейся, а сам -- не плошай. Лишний коментарий еще никогда не вредил, а экономия на "дисковом пространстве" (да, была и такая отговорка) всегда выходит себе дороже. При этом комментарий должен описывать "зачем это делается", а не совершенно очевидное из кода "присвоим переменной зю значение 3.1415926".
blueher at 2011-06-19 19:23 (UTC) (Link)
Да, часто такое в комментариях к коду (и это единственный вид комментариев который имеет смысл писАть). Но не менее часто это отдельный документ который в коде просто затеряется - потому что код большой и размазывать по нему знание как это всё устроено - нецелесообразно. Да и рисовать картинки в комментариях - тоже не очень удобно, а человек картинки воспринимает куда лучше чем буковки...
Gaperton
gaperton at 2011-06-19 19:57 (UTC) (Link)
Картинки рисовать нет никакого смысла - они извлекаются из кода тулами автоматически, и будут всегда актуальны. Для С++ это отлично делает Rational Rose. Любая class-диаграмма рисуется в минуты, так что глупо на "документирование" этого время тратить.

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

Все.
blueher at 2011-06-19 20:21 (UTC) (Link)
Картинки - это далеко не всегда диаграмма классов и им подобные (которые генерируются по коду в любой момент).
Часто нужно "обрисовать" предметную область.
hedgeov
hedgeov at 2011-06-19 20:16 (UTC) (Link)
Есть великая штука -- doxygen, а в ней великая штука dot. Очень помогает. Картинки -- загляденье, даже через год.
blueher at 2011-06-19 20:23 (UTC) (Link)
Мне не нужны диаграммы классов, мне их IDE покажет в любой момент. А вот картинки которые расскажут мне о предметной области (ну к примеру какие названия у меня что обозначают) - часто стОят кучи страниц текста.
hedgeov
hedgeov at 2011-06-19 20:26 (UTC) (Link)
Так я как раз о том, что с помощью нотации dot и надо в комментариях рисовать те самые картинки предметной области. Диаграммы классов doxygen и сам по коду нарисует.
Gaperton
gaperton at 2011-06-19 20:29 (UTC) (Link)
Смысла в этом нет ровным счетом никакого.

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

И это произойдет само собой.
hedgeov
hedgeov at 2011-06-19 20:37 (UTC) (Link)
Мне кажется полезным иметь "прямо в коде" ссылку на релевантный кусочек предметной области, чтобы не лазать в трекер лишний раз. Опять же, маньяков от документации можно нейтрализовать.
Хотя возможно ты прав, надо попробовать конкретизировать комментарии к тикетам и коммитам...
Gaperton
gaperton at 2011-06-19 21:31 (UTC) (Link)
> Мне кажется полезным иметь "прямо в коде" ссылку на релевантный кусочек предметной области, чтобы не лазать в трекер лишний раз.

Конечно, два раза в гиперссылку жамкнуть, глядя на код - это очень сложно, а вот ручками поддерживать актуальность комментария о постановки задачи, делая вручную работу системы контроля версий и трекера - не в лом. Это кажется полезным.

Я поражаюсь парадоксальному складу ума программистов.
Previous Entry  Next Entry