Документированность кода

By Balancer: вынесено из Форумы Авиабазы

---

Balancer, 07.06.2004 20:06:42 :

hcube, 07.06.2004 19:10:33 :

а программисту оно зачем?

 

Отчёты писать понятные. А то такого могут понаписать, как хочешь, так и понимай

 

Не, отчёты должен писать сторонний человек.
Просто автор пишет опуская то, что считает само мобой разумеющимся. А пользователь натыкается...
Я не программист, но вот непонятливость читающих написанную мной документацию просто переходит все границы!

>Отчёты писать понятные. А то такого могут понаписать, как хочешь, так и понимай

Умный догадается, а дураку не надо. Шутка, есс-но.

hcube, 08.06.2004 05:12:24 :

Отчеты - это конечно полезно - но для программиста это лишь второстепенная задача. Примерно как отчетность по расходу краски и холста для художника. А первостепенная - писать надежный, быстрый, компактный - и только потом - документированый код.

 

Это для гениев-одиночек . А для большой команды, и тем более для компании, очень мало толку будет от хорошего, но недокументированного кода.

>Я лично знаю литературный довольно хорошо, ...
>Правда я средний очень много что, так что мозги у меня развиты примерно одинаково

Гы-гы (с)

Посмотри с другой стороны - что толку в хорошо документированом, но дерьмово написанном коде? Не, сапожник должен именно сапоги тачать .

Относительно работы в команде - есть соглашение об ИНТЕРФЕЙСАХ. ТО есть если функцию вызвать так-то, то делает она то-то. А как это будет реализовано - на сях, бейсике, паскакале, хранимых SQL-процедурах, или вообще внешним механическим устройством - никого не волнует. . Еще могу сказать, что хорошо написанный код... эээ... самодокументирован - достаточно просто читается.

hcube, 08.06.2004 10:18:54 :

Посмотри с другой стороны - что толку в хорошо документированом, но дерьмово написанном коде?

 

В таком коде - море бабок. ИМХО, ты сейчас в таком коде и пишешь

Но, повторюсь, тут не причинноследственная зависимость, а корреляция. Обычно хорошие программисты и языком владеют. А кулхацкеры - редко бывают хорошими программерами

hcube, 08.06.2004 10:18:54 :

Еще могу сказать, что хорошо написанный код... эээ... самодокументирован - достаточно просто читается.

 

Это сильно зависит от языка.

На сегодняшний день хороших и распространённых самодокументирующихся языков просто нет.

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

Balancer, 08.06.2004 09:24:23 :

hcube, 08.06.2004 10:18:54 :

Посмотри с другой стороны - что толку в хорошо документированом, но дерьмово написанном коде?

 

В таком коде - море бабок. ИМХО, ты сейчас в таком коде и пишешь

 

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

Да, вынеси плиз обсуждение документирования кода в отдельную ветку, ок?

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

Фрагменты того, с чем развлекаюсь сейчас я:

// ShowDetailsWindow1Click ----------------------
void __fastcall TForm1::ShowDetailsWindow1Click(TObject *Sender)
{
char NewTitleForDetailsForm[200];
if (lStartTime>lEndTime) {long t=lEndTime; lEndTime=lStartTime;lStartTime=t;};
if (lStartTime==lEndTime) {lEndTime=lStartTime+1+TDetailsForm::WinWidthSec;};
....

Комментарии вставляются только там, где без них трудно.

гм..все таки венгерская нотация хорошая вещь. а то так и не поймешь к чему относятся lEndTime, lStartTime. а форматирование у вас не такое же как отображено здесь?

ИМХО - нужна разумная достаточность.
Документировать нужно то, что требуется понять кому-то другому.
Т.е. каждую операцию - нет
А вот например объект/функцию - да.
И надо помнить, что в нынешних нестабильных условиях (когда через год уже и процессор, и ОС, и компилятор другие) делать ещё и документирование - значит напрасно тратить время, всё равно придётся переписывать...

Dem_anywhere, 08.06.2004 15:38:14 :

А вот например объект/функцию - да.

 

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

2 Филич
Ну, декларации классов же в другом месте...

Поскольку я с Торвальдсом не согласен (насчет табуляции 8), то таб стопы у меня кратны трём.
А мой стиль носит очевидные родимые пятна Паскаля...

Vale, 08.06.2004 14:08:11 :

Фрагменты того, с чем развлекаюсь сейчас я:

 

мои коды ничем не примечательны, банальный PHP. От венгерской нотации даже ничего нет, разве что имена клаасов - капитализированные, а переменных - с подчерками

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

1. \ слово вращает координаты точек массива 10точек[num]
2. \ относительно точки 0,0 на угол УГОЛ в градусах
3. : точек_поворот ( num -- )
4.   0
5.   DO
6.     I -й точка.х @  УГОЛ @ COS*  I -й точка.у @  УГОЛ @ SIN* +   (  точка.х  )
7.     I -й точка.у @  УГОЛ @ COS*  I -й точка.х @  УГОЛ @ SIN* -   (  точка.х,точка.у )
8.     I -й точка.у !
9.     I -й точка.х !
10.   LOOP
11. ;
12. \  слово рисует циферблат
13. \  должна быть установлена переменная РИС
14.  
15. : рисовать_циферблат
16.   10точек TO ГРУППА_ТОЧЕК \ вращение структуры /PAINT
17.   60 0
18.   DO
19.     I 6 * УГОЛ !
20.       0 0 -й точка.х !
21.     900 0 -й точка.у !
22.     1 точек_поворот
23.     УГОЛ @ 5 MOD
24.     0=  IF   100          \ диам точек часов
25.         ELSE 33 THEN      \ диам точек минут
26.     DUP 2 -й точка.х !    \ запишем в массив
27.         2 -й точка.у !
28.     \ эквивалент C: pt[0].x -= pt[2].x / 2 ;
29.     0 -й точка.х DUP @  2 -й точка.х @ 2 /  -  SWAP !
30.     0 -й точка.у DUP @  2 -й точка.у @ 2 /  -  SWAP !
31.     \
32.     0 -й точка.х @  2 -й точка.х @ +  1 -й точка.х !
33.     0 -й точка.у @  2 -й точка.у @ +  1 -й точка.у !
34.     \
35.     ЧЕРНЫЙ_ЦВЕТ GetStockObject  РИС @ SelectObject DROP
36.     1 -й точка.у @ 1 -й точка.х @ 0 -й точка.у @ 0 -й точка.х @ РИС @
37.     Ellipse DROP
38.   LOOP
39.   ;
40. \ набор данных для изображения стрелок часов
41. HERE
42.   0 , -150 , 100 , 0 , 0 , 600 , -100 , 0 , 0 , -150 ,
43.   0 , -200 ,  50 , 0 , 0 , 800 ,  -50 , 0 , 0 , -200 ,
44.   0 ,    0 ,   0 , 0 , 0 ,   0 ,    0 , 0 , 0 ,  800 ,
45. CONSTANT СТРЕЛКИ

И т.д.

Vale, 08.06.2004 17:43:40 :

Поскольку я с Торвальдсом не согласен (насчет табуляции 8)

 

А он чего, за табуляцию в 8 ратует?

А, вообще, из активных соглашений на счёт отступов только стандарт PEAR в голову приходит, там строго 4 пробела. И никаких символов табуляции

Ну, вообще в GNU и в Linux в частности принята не устраивающая меня нотация. (Чтобы субмиттить код в kernel, к примеру). В том числе там требование к табуляции в 8, и форматирование циклов какое-то своё... В теории-то я с ними согласен , но на практике делаю по-своему . Как привык.

Есть такая штука - literate programming, ещё одно изобретение Дональда Кнута. Так там документация - интегральная часть исходников. И программы выглядят идейно так: "Сейчас мы расскажем, что мы тут собираемся делать. Нам нужна переменная, показывающая количество элементов в нашем контейнере. Для обеспечения независимого доступа из различных процессов мы ставим защиту на эту переменную." synchronized int nElements;




Мне такой код нравится тем, что после полугодового отсутствия приходишь обратно к собственному коду и быстро разбираешься, что и почему тут было сделано. В принципе, достаточно далеко продвинутая идея о встроенной документации. ЯВУ вообще в основном строятся для удобства человеку решать определённые классы задач; документация - просто ещё одно удобство.

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

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

Vale
про классы это понятно. просто часто переменные-члены класса обозначают как то. или m_* или просто _* .

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

Guest, 08.06.2004 21:19:43 :

ну проект его как бы проектировать надо.

 

Это, извините, тавтология. Хотел бы я глянуть, как вы "проектировать проект" будете без документации.

[quote|Филич, 09.06.2004 09:17:03 :]вообще странный спор о том, что не надо комментировать исходники. в рассматриваемом через полгода после написания коде иногда сложно уловить мысль, витавшую в момент его написания. так что без комментов никуда[/quote]

Точно, есть такое. Но проблема не в отсутствии коментариев, а в необходимости в них! Надо создавать такой код, чтобы у него был "вход", "выход" и "кнопка". На перечисленное должна быть документация в начале кода, как и описание что это такое, зачем оно, как пользоваться и т.д. Это должна быть вестчъ, а не рассыпанный конструктор.

au

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

 

именно так и описывается в хидерах. типа такого:

1.    //********************************************************    
2.    //  Name:       GetResource()
3.    //
4.    //  Abstract:
5.    ///             Takes a decoder to use for given session.
6.    ///             Returns a pointer to a new instance of this decoder,
7.    ///             or 0 if instantiation or reservation fails.
8.    //
9.    //  Input:      See the parameter comments below.
10.    //
11.    //  Output:     See Abstract above.
12.    //
13.    //  Calls:      See the Doxygen Documentation [1].
14.    //
15.    //  Remarks:    -
16.    //********************************************************    
17.    virtual CResource *
18.    GetResource(
19.               const CResourceSpec &ResourceSpec
20.                                 ///< Argument object that specifies the
21.                                 ///< properties of the resource including
22.                                 ///< the session taking the resource to use
23.     );

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

[quote|Филич, 09.06.2004 10:07:44 :]а уж внутри функций тоже необхдимо пояснять почему сделано так, а не иначе.[/quote]

Вот это как раз и лишнее. Это же не учебник, не наглядное пособие. Это машина, или агрегат машины. На коробке передач в машине тоже надо сборочный чертёж с мемуарами коллектива разработчиков изображать? Абсурд, ибо это есть вещь, и она работает, а как и почему — это дело десятое.
Конечно, если корпоративная политика заставляет, это другое дело.