Посоветуйте систему автоматизации документирования кода

← →
Kostafey © (2008-06-02 21:02) [0]

Их несколко есть. Robodoc, в Java - Javadoc, etc.
С какими вы работаете, что рекомендуете изучать,
использовать?

← →
tesseract © (2008-06-02 22:03) [1]

Их имеет смысл использовать только проекта больше 50 тысяч строк. Под делфи TeamSource вроде отлично справляеться.

← →
Kostafey © (2008-06-02 22:11) [2]

> Их имеет смысл использовать только проекта больше 50 тысяч
> строк.

Ну столько-то есть. Может больше. Посчитаю.

> Под делфи TeamSource вроде отлично справляеться.

Да я не про дельфи. Я скорее про универсальные инструменты.

← →
Kostafey © (2008-06-02 22:18) [3]

Да и вообще, если проект имеет столько-то там строк,
а в по ниму ни буквы документации - это не есть хорошо.

Если я правильно понимаю она долна составляться по ходу кодирования.
Так что это скорее урок на будущее, чем камень на шею
текущему проекту.

← →
Sergey Masloff (2008-06-02 22:24) [4]

Я не вижу особого смысла в такого рода документации (хотя какое-то время назад был увлечен этой идеей и в ряд наших проектов внедрил). В принципе тот формат что используется в JavaDoc можно использовать для разных языков. Конечно "изучать" довольно громкое определение для спецификации из пары страниц. Инструменты ищутся поиском для нужной среды за полчаса. Для Delphi например DelphiDoc и DelphiCodeToDoc - я использовал оба какой-то из них удобнее но сейчас не помню какой.
Но лично я на данный момент считаю что толку в такой низкоуровневой "документации" немного.

← →
Kostafey © (2008-06-02 22:33) [5]

> [4] Sergey Masloff (02.06.08 22:24)

Спасибо, интересная точка зрения.

Я подумал еще о двух вещах:
1). Может такого рода документирование стоит
использования для описани более высокоуровневых
элементов. Т.е. не что этот код делает,
а для чего он нужен. Т.е. описанние бизнес-
логики.
2). Кодирование с пониманием того, что будет
генериться документация заставит разработчиков
лучше "вылизывать" код, писать подробные коментарии,
etc...

← →
Игорь Шевченко © (2008-06-02 23:03) [6]

Пример хорошей документации в коде - комментарии в коде Unix.

> 1). Может такого рода документирование стоит
> использования для описани более высокоуровневых
> элементов. Т.е. не что этот код делает,
> а для чего он нужен. Т.е. описанние бизнес-
> логики.

Самой хорошей документацией будет описание, почему без этого кода нельзя обойтись. Любая остальнаz документация будет, скорее всего, никогда не читаемым мусором, геморроем для разработчиков и просто пустой тратой времени.

> 2). Кодирование с пониманием того, что будет
> генериться документация заставит разработчиков
> лучше "вылизывать" код, писать подробные коментарии,
> etc...

не верю! (с) Станиславский

И вообще, любая автоматически составляемая/генерируемая по коду документация полезна, максимум, в случае рефакторинга.

← →
Palladin © (2008-06-02 23:18) [7]

>И вообще, любая автоматически составляемая/генерируемая по коду документация полезна, максимум, в случае рефакторинга.

то то я чуть не свихнулся пока описывал модель данных в одном проекте, не позаботившись об описании ее в коде заранее... :) а всего лишь к проекту добавился, кроме меня, еще один человек

← →
Игорь Шевченко © (2008-06-02 23:28) [8]

Palladin © (02.06.08 23:18) [7]

А кто говорит, что писать документацию легко ? :)

Вот, например, та же VCL - в коде комментариев код наплакал, зато отдельный Help по всем классам, с картинками. Не дай Аллах, все содержимое Help-а в коде было - код был был абсолютно нечитаем.

← →
Eraser © (2008-06-03 00:33) [9]

> [6] Игорь Шевченко © (02.06.08 23:03)

> И вообще, любая автоматически составляемая/генерируемая
> по коду документация полезна, максимум, в случае рефакторинга.

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

← →
Германн © (2008-06-03 00:56) [10]

> Игорь Шевченко © (02.06.08 23:28) [8]
>
> Palladin © (02.06.08 23:18) [7]
>
> А кто говорит, что писать документацию легко ? :)
>

+1
:((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((

← →
Тимохов (2008-06-03 01:31) [11]

по себе скажу.

я для себя разделяю доку на 3 виду (2 вида доки - это комменты в коде. 1 вид - ворд):

1. вид 1 - удобство чтения кода.
Например:
// Коэффициент мгновенной ликвидности
... это я пишу перед расчетом той самой ликвидности, сами понимаете втыкать по месту перевод термина с инглиша не всегда есть гуд.

// Шаг III. Построение контольного кода
... это я использую в длинных процедурах (вопреки заверениям монстров я их использую в *некоторых* случаях, когда овощь к столу).

// Параметры: // 1. Target - объект, где нужно сделать то-то // и то-то... бла-бла-бла. За уничтожение отвечат // тек. объект. // 2. Operation - что нужно сделтать с объектом. // Если равно opNew, то параметр Info д.б. равен // идентификатору создаваемого объекта. // 3. Info - доп. инфо. См. описание пр-ра. Operation. procedure MakeTargetCool(Target: TObject; Operation: TOperation; Info: INteger);

Ну тут понятно - описываю все, что пишу. Я взял за правило - ДО нажатия RUN, описать все, что сделал в упомянутом стиле. Русский язык побоку - главное, чтобы было понятно.

2. Вид 2 - пояснение нафига строка, вроде бы можно без нее?

Например:

{ Нафига строка? Ну просто я не знал, как открыть TFileStream для создания нового файла с разрешением его чтения. Поэтому сначала создаю поток, потом закрываю, потом открываю уже для чтения и с возможностью чтения другими. Если знаете, как сделать иначе, то сделайте. 2do - сделать иначе, если буду знать как }

... тут понятно - поясняю нафига нужна строка, в общем-то с первого взгляда "левая".

и все в таком духе - объяснить "левую" строку.

Вид 3 - word

Ну тут все понятно. Пишу обычно так - эта штука юзает эту штуку (утрирую), т.к. хочет от нее получить данные клиента. И все в таком стиле. Минимум деталей, минимум тонкостей. Дока в словах должна внести в голову читателя информацию о том, что нафиг это все такое. Кто кого юзает, кто зачем создан.

КСТАТИ, возникает вопрос - как читатель кода поймет, что нужно читать что-то еще? Я для этого сделал 2 вещи:
1. Сделал плугин, который зарегил как протокол в ОС. Теперь моя ОС знает, что если в ShellExecute дать "tech-doc://bla-bla-bla", то нужно вызвать определенную программу, которая знает, что с этим "bla-bla-bla" делать.
2. Написал расширение IDE, которое вызывает этот tech-doc при нажатии определенного сочетания клавиш.
-------------------

МОЙ РЕЗЮМ.
Каждый проект имеет свою методику. И ни одна из стандарных методик не превосходит твоего личного понимания документирования проекта. Надо много думать и много пытаться сделать удобно.

Поставь себя на место разработчика, который получил все твои исходинки и хорошую з/п, чтобы поддерживать и развивать их. Что он должен делать? У меня (если он, конечно не идиот) он прочтет файл !!!readme.txt в корне проекта. Там должно быть все сказано, что делать дальше.

Если ты не можешь ввести своей докой в курс дела новичка, то твоя дока ничего не стоит. ИМХО.

← →
Тимохов (2008-06-03 01:39) [12]

Еще добавлю.

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

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

Я вот тут ICS почитываю (это фришные сетевые компоненты). Нет никакой возможности описать их хорошо, ибо понимание базовых вещей в данной либе есть своего рода входной билет в пользователей либы :) Это я к тому, что всегда можно понять, что он делает по тем РЕДКИМ коментам, которые есть в коде.

-------------
РЕЗЮМ (надеюсь, что окончательный)

Писать нужно редко но метко в СИСТЕМНЫХ либах,
и часто и много в прикладных либах, в которых объем знаний лежит МНОГО выше кода (например, та же бухгалтерия).

В случае алгоритмического кода имеет смысл ознакомится с литературным программированием:

http://literateprogramming.com
http://literateprogramming.com/knuthweb.pdf

> Игорь Шевченко © (02.06.08 23:28) [8]

ну как сказать... дело в том, что исходные тексты ему ни к чему (соответственно я их ему и не дал :) ), а описаловку сделать нужно, причем мягко обойти те моменты которые в пререлизе и не документированны, соответственно пользоваться ему ими не надобно... в общем говоря, именно описание API, которым он уже пользуется при построении интерфейса приложения... вот тут как раз вдруг понадобилось автодокументирование :) пришлось в срочном порядке документировать в исходниках... а по поводу исходников VCL, я что то все же склоняюсь, что к нам они не в исподнем, а в товарном виде попадают :) хто с уверенностью сказать может...

Palladin © (03.06.08 15:26) [15]

> а описаловку сделать нужно, причем мягко обойти те моменты
> которые в пререлизе и не документированны, соответственно
> пользоваться ему ими не надобно... в общем говоря, именно
> описание API, которым он уже пользуется при построении интерфейса
> приложения...

Вот это руками и делается :)

> а по поводу исходников VCL, я что то все же склоняюсь, что
> к нам они не в исподнем, а в товарном виде попадают :) хто
> с уверенностью сказать может...

Ты всерьез полагаешь, что в Borland, а ныне в Codegear есть бригада людей, которые занимаются вычищением комментариев из кода ? :)
У меня почему-то нет такой уверенности...

> Ты всерьез полагаешь, что в Borland, а ныне в Codegear есть
> бригада людей, которые занимаются вычищением комментариев
> из кода ? :)
> У меня почему-то нет такой уверенности...

да почему, инструментами все делается, инструментами...
да и не полагаю, а предполагаю... :)

> [13] Mystic © (03.06.08 10:03)
> В случае алгоритмического кода имеет смысл ознакомится с
> литературным программированием:
>
> http://literateprogramming.com
> http://literateprogramming.com/knuthweb.pdf

Прочитал. Сильная штука.

Сначала подумал, свежая статейка, ну подумаешь,
консервативная, вышла ж из университеской среды.

Но натыкаюсь:
I chose the name WEB partly because it was one of
he few three-letter words of English that hadn’t al-
eady been applied to computers.

Смотрю в конце:
Received September 1983

Все же при детальном изучении пока не могу понять
какое это может найти применение в современном программировании.
Слишком... неестественно.

Классическое структурное программирование с развернутыми
комментариями в коде как-то привычнее.

Такой результат ничто не оправдывает:

Figure 3. PASCAL program generated from the WEB file.

{1:}{2:}PROGRAM PRINTPRIMES(OUTPUT);
CONST M=1000;{5:}RR=50;CC=4;WW=10;{:5}{19:}
ORDMAX=30;{:19}VAR{4:}
P:ARRAY[1..M]OF INTEGER;{:4}{7:}
PAGENUMBER:INTEGER;PAGEOFFSET:INTEGER;
ROWOFFSET:INTEGER;C:0..CC;{:7}{12:}J:INTEGER;
K:0..M;{:12}{15:}JPRIME:BOOLEAN;{:15}{17:}
ORD:2..ORDMAX;SQUARE:INTEGER;{:17}{23:}
N:2..ORDMAX;{:23}{24:}
MULT:ARRAY[2..ORDMAX]OF INTEGER;{:24}
BEGIN{3:}{11:}{16:}J:=1;K:=1;P[1]:=2;{:16}
{18:}ORD:=2;SQUARE:=9;{:18};
WHILE K<M DO BEGIN{14:}REPEAT J:=J+2;{20:}
IF J=SQUARE THEN BEGIN ORD:=ORD+1;{21:}
SQUARE:=P[ORD]*P[ORD];{:21}{25:}
MULT[ORD-1]:=J;{:25};END{:20};{22:}N:=2;
JPRIME:=TRUE;
WHILE(N<ORD)AND JPRIME DO BEGIN{26:}
WHILE MULT[N]<J DO MULT[N]:=MULT[N]+P[N]+P[N]
;IF MULT[N]=J THEN JPRIME:=FALSE{:26};N:=N+1;
END{:22};UNTIL JPRIME{:14};K:=K+1;P[K]:=J;
END{:11};{8:}BEGIN PAGENUMBER:=1;
PAGEOFFSET:=1;
WHILE PAGEOFFSET<=M DO BEGIN{9:}
BEGIN WRITE(’The First ’);WRITE(M:1);
WRITE(’ Prime Numbers --- Page ’);
WRITE(PAGENUMBER:1);WRITELN;WRITELN;
FOR ROWOFFSET:=PAGEOFFSET TO PAGEOFFSET+RR-1
DO{10:}
BEGIN FOR C:=0 TO CC-1 DO IF ROWOFFSET+C*RR<=
M THEN WRITE(P[ROWOFFSET+C*RR]:WW);WRITELN;
END{:10};PAGE;END{:9};
PAGENUMBER:=PAGENUMBER+1;
PAGEOFFSET:=PAGEOFFSET+RR*CC;END;END{:8}{:3};
END.{:2}{:1}

Посоветуйте систему автоматизации документирования кода Найти похожие ветки