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

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

Dem_anywhere, 09.06.2004 12:44:56 :

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

 

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

И т.д. и т.п.

au

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

 

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

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

А UML - это не описание (если только не рассматривать одни диаграмки), а все же модель и код - это часть ее.

1. Стараюсь. На всех проектах, что работал всегда поддиректория с черновиками в системе хранения сорцов. Плюс всегда пишу документы, почему принял такое решение. В коде обычно стараюсь ключевые моменты описать. Даже часто комментриую комментарии при изменении кода. Правда читают их очень не большое количество человек. Скажем, в саппорте, только один человек, но сказал намного понятнее сразу стало, почему писано так, а не этак. Есть еще одна проблема, как только код ушел в саппорт - они такую доку не поддерживают, а исправления накапливаются.

2. В UML - не скажу, что много делал, но поскольку с параллельными процессами вожусь, то всяческие диаграмки временного взаимодействия тоже пишу. Всякие use case делаю - больно тестировать на автомате хорошо. Но, вот для СУБД - я сейчас вовсю Erwin использую и всю группу под зад пихаю в этом направлении. Благо, что производится нашей компанией и доступен для меня бесплатно. А вот с Rational Rose проблема, т.к. наша контора делает свой продукт - Paradigm Plus, а он мне нравиться меньше. Хотя тоже бесплатен для меня.

Вот кусочек кода как я пишу:

1. ...
2.  
3.     protected:
4.         // VCS tree - each VCS could have sub-VCS's through list member
5.         // each VCS has a pointer to a parent - parent member
6.         // if parent is NULL then it's a root (belongs to a probe).
7.         MIBVCS list;
8.         VCS* parent;
9.  
10.  
11.         probe_status *probe; // each VCS has a pointer to a parent structure. It's neccessary to be able to get
12.                                         // some information - ip, public string, etc.
13.         SmartCollection extra; // some extra elements - currently all index parts that are not parts of polls.
14.         SmartCollection configPoll; // Configuration record
15.         SmartCollection statPoll;       // statistical record
16.         vcsCollection   configRecord; // collection of binds should be written to a DB
17.         vcsCollection   statRecord;     // ditto
18.         vcsCollection   indexRecord;    // fast access to index values
19.  
20.         SmartCollection setColl;        // all VarBinds from this collection which are subject to set command
21.  
22.         // index is a separate issue - it comprises rows of values.
23.         // for now - it's a vector of C-strings - we extract it always from the response
24.         // and keep it here.
25.         idxHolder               indexTable;
26.  
27. ...
28.  
29. // make a parent from the first child
30. // if there is no child - return NULL
31. VCS* VCS::MakeNewParent( void )
32. {
33.     if ( list.empty( ) ) return NULL;
34.  
35.     GrabSync( );
36.  
37.     VCS* v = list[ 0 ];
38.  
39.     // first of all, make a child looks like a parent
40.     v->parent = NULL;
41.  
42.     // delete it from the list so it will not refer to itself
43.     list.erase( list.begin( ) );
44.  
45.     // copy list
46.     v->list = list;
47.     // and erase it so all members woun't get deleted in the destructor.
48.     list.erase( list.begin( ), list.end( ) );
49.  
50.     ReleaseSync( );
51.  
52.     // now go through the list and substitute parent reference
53.     v->GrabSync( );
54.     int size = v->list.size( );
55.     for ( int i = 0; i < size; ++i )
56.     {
57.         v->list[ i ]->parent = v;
58.     }
59.     v->ReleaseSync( );
60.  
61.     return v;
62. }

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

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

UML - вещь не плохая, но увы не всегда. Пример, попробуйте обосновать выбор того или иного алгоритма сортировки в программе только с помощью UML. не очень доходчиво получается. И второе, как Mishka уже заметил, это изменения в коде. Надо где-то писать что поменяли и почему. Можно же не просто баг зафиксить простейший, а поменять не совсем очевидные вещи. Порядок выбора элемента, стратегию оптимизации. И надо писать где, что и главное ПОЧЕМУ.

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

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