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

 
RU Alesandro #07.06.2004 20:36
+
-
edit
 

Alesandro
Серокой

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



Balancer, 07.06.2004 20:06:42 :
hcube, 07.06.2004 19:10:33 :
а программисту оно зачем?
 


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


Не, отчёты должен писать сторонний человек.
Просто автор пишет опуская то, что считает само мобой разумеющимся. А пользователь натыкается...
Я не программист, но вот непонятливость читающих написанную мной документацию просто переходит все границы! :-D
Больше не раскалятся ваши колосники. Мамонты пятилеток сбили свои клыки. ©  
Это сообщение редактировалось 08.06.2004 в 10:38
+
-
edit
 

AidarM

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

Умный догадается, а дураку не надо. :D Шутка, есс-но.
Солипсизм не пройдёт! :fal:  

Zeus

Динамик

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


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

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

Гы-гы (с) :D
И животноводство!  

hcube

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

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

Balancer

администратор
★★★★☆
hcube, 08.06.2004 10:18:54 :
Посмотри с другой стороны - что толку в хорошо документированом, но дерьмово написанном коде?
 


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

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

Balancer

администратор
★★★★☆
hcube, 08.06.2004 10:18:54 :
Еще могу сказать, что хорошо написанный код... эээ... самодокументирован - достаточно просто читается.
 


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

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

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

hcube

старожил
★☆
Balancer, 08.06.2004 09:24:23 :
hcube, 08.06.2004 10:18:54 :
Посмотри с другой стороны - что толку в хорошо документированом, но дерьмово написанном коде?
 


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


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

Убей в себе зомби!  

hcube

старожил
★☆
Да, вынеси плиз обсуждение документирования кода в отдельную ветку, ок?
Убей в себе зомби!  
?? Филич #08.06.2004 10:52
+
-
edit
 

Филич

втянувшийся

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

Vale

Сальсолёт

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

// 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;};
....

Комментарии вставляются только там, где без них трудно.
"Не следуй за большинством на зло, и не решай тяжбы, отступая по большинству от правды" (Исх. 23:2)  
?? Филич #08.06.2004 15:50
+
-
edit
 

Филич

втянувшийся

гм..все таки венгерская нотация хорошая вещь. а то так и не поймешь к чему относятся lEndTime, lStartTime. а форматирование у вас не такое же как отображено здесь?
существуют только два типа кораблей: подводные лодки и их цели
 
RU Dem_anywhere #08.06.2004 16:38
+
-
edit
 

Dem_anywhere

аксакал

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

Andy-Andrei

втянувшийся

Dem_anywhere, 08.06.2004 15:38:14 :
А вот например объект/функцию - да.
 


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

Vale

Сальсолёт

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

Поскольку я с Торвальдсом не согласен (насчет табуляции 8), то таб стопы у меня кратны трём.
А мой стиль носит очевидные родимые пятна Паскаля...
"Не следуй за большинством на зло, и не решай тяжбы, отступая по большинству от правды" (Исх. 23:2)  
+
-
edit
 

Balancer

администратор
★★★★☆
Vale, 08.06.2004 14:08:11 :
Фрагменты того, с чем развлекаюсь сейчас я:
 


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

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

code forth
  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 СТРЕЛКИ


И т.д. :)
 
+
-
edit
 

Balancer

администратор
★★★★☆
Vale, 08.06.2004 17:43:40 :
Поскольку я с Торвальдсом не согласен (насчет табуляции 8)
 


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

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

Vale

Сальсолёт

Ну, вообще в GNU и в Linux в частности принята не устраивающая меня нотация. (Чтобы субмиттить код в kernel, к примеру). В том числе там требование к табуляции в 8, и форматирование циклов какое-то своё... В теории-то я с ними согласен :D , но на практике делаю по-своему :F . Как привык.
"Не следуй за большинством на зло, и не решай тяжбы, отступая по большинству от правды" (Исх. 23:2)  
Это сообщение редактировалось 08.06.2004 в 21:32
Vale, 08.06.2004 20:26:19 :
Ну, вообще в GNU и в Linux в частности принята не устраивающая меня нотация. (Чтобы субмиттить код в kernel, к примеру). В том числе там требование к табуляции в 8, и форматирование циклов какое-то своё... В теории-то я с ними согласен :D , но на практике делаю по-своему :F . Как привык.
 


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

http://www.slm.wau.nl/wkao/DelForExp.html

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


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

http://zone1c.narod.ru/docs/uml/uml_index.htm

вроде там розочка рулит


UML диаграммы в  Rational Rose

Примеры UML диаграмм, которые поддерживает Rational Rose

// www.caseclub.ru
 

 
+
-
edit
 

avmich

координатор

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


Literate Programming

Learn about literate programming using the CWEB tool for software development. Download a free CWEB distribution for Microsoft Windows

// www.literateprogramming.com
 



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

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

По поводу форматирования вообще религиозные войны бушуют. Вроде бы хорошим решением является каждому иметь себе свой собственный форматтер, который форматирует код под свой вкус. Получается, что каждый всегда работает с кодом, организованным в лучшей для него форме. Такой же форматтер надо иметь на сервере контроля версий, чтобы не было иллюзий, что каждое изменение кода затрагивает файл целиком. Форматтерам, конечно, приходится быть достаточно умными :) .
 
?? Филич #09.06.2004 10:17
+
-
edit
 

Филич

втянувшийся

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

вообще странный спор о том, что не надо комментировать исходники. в рассматриваемом через полгода после написания коде иногда сложно уловить мысль, витавшую в момент его написания. так что без комментов никуда :)
существуют только два типа кораблей: подводные лодки и их цели
 
RU Andy-Andrei #09.06.2004 10:30
+
-
edit
 

Andy-Andrei

втянувшийся

Guest, 08.06.2004 21:19:43 :
ну проект его как бы проектировать надо.
 


Это, извините, тавтология. Хотел бы я глянуть, как вы "проектировать проект" будете без документации.
Ты не смотри, что у меня вечно штраф висит... Я не буйный...  

au

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

Точно, есть такое. Но проблема не в отсутствии коментариев, а в необходимости в них! Надо создавать такой код, чтобы у него был "вход", "выход" и "кнопка". На перечисленное должна быть документация в начале кода, как и описание что это такое, зачем оно, как пользоваться и т.д. Это должна быть вестчъ, а не рассыпанный конструктор.
 
?? Филич #09.06.2004 11:07
+
-
edit
 

Филич

втянувшийся

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


именно так и описывается в хидерах. типа такого:
code text
  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.     );


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

au

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

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

в начало страницы | новое
 
Поиск
Настройки
Твиттер сайта
Статистика
Рейтинг@Mail.ru