?

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 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