Документрирование и "дурно пахнущий код".

← →
by © (2004-09-22 16:12) [0]

У Фаулера, в "Рефакторинг" одна из основных идей - это то что дурно пахнущий код (в котором много комментариев) нужно переписывать чтобы код сам себя описывал. Т.е. многие участки кода должны вырождаться в функции, имя которых ибъясняет их назначение. Но нужно ли функции документировать, т.е. применяете ли вы для документирования функций какой-то стандарт или все остается без документирования и комментариев.
Применяется ли, например такое:
Заголовок модуля:

unit uFrm_BaseForm;
{****************************************************
Модуль: uFrm_BaseForm
Copyright (c) 2004 ...
Департамент разработки ПО
Разработчик: ...
Назначение: Базовая форма проекта. Данная форма служит родителем для остальных и содержит в себе методы и компоненты для сохранения настроек в ини-файле. Любая форма-наследник может быть представлена как самостоятельное окно при использовании стандартного конструктора или как фрейм - внедрённая в объект типа TPanel
История:
10.05.2004 - Создан
03.06.2004 - добавлены новые конструкторы с передачей массива параметров
10.06.2004 - Подправлен RunForm
*******************************************************}

Заголовок функции
{********************************************************
Процедура/функция: Create
Разработчик: ...
Назначение: конструктор с параметрами
IN : AOwner - владелец формы
AParent - контрол в который внедряется форма
AavParams - параметры для формы
OUT : None
RET : None
История:
31.05.2004 - Создана
*******************************************************}
constructor Create(AOwner: TComponent; AParent: TWinControl; AavParams: array of variant); reintroduce; overload;

Заголовок хранимой процедуры
/******************************************************
SP_CM_CREATE_BILLS
BY ...

Создание счетов в закрытии месяца

IN : A_D_BILL_DT - Дата счета
: A_I_BILL_FIRST_NMB - Первый номер счета
: A_V_BIIL_NMB_SUFFIX - Суффикс номера счета
: A_D_BGN_DT - Дата начала периода за который берутся начисления
: A_D_END_DT - Дата окончания периода за который берутся начисления
: A_I_TP_WORK_UNIT_ID - тип номера

OUT : NONE

NOTES :
********************************************************/

Как Вы поступаете?

← →
Гаврила © (2004-09-22 16:35) [1]

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

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

← →
Гаврила © (2004-09-22 16:38) [2]

А тут что получается

Процедура/функция: Create /// Это и так написано ниже Разработчик: ... /// Чаще всего не важно Назначение: конструктор с параметрами /// это и так понятно
IN : AOwner - владелец формы /// И это тоже и так понятно
AParent - контрол в который внедряется форма /// И это тоже
AavParams - параметры для формы // А вот это непонятно, несмотря на комментарий

constructor Create(AOwner: TComponent; AParent: TWinControl; AavParams: array of variant); reintroduce; overload;

← →
vecna © (2004-09-22 16:43) [3]

имхо такой вариант издевательство, слишком много лишней информации...

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

вся остальная инфа: кто, когда, зачем и почему (в т.ч. история) хранится в vss

← →
DiamondShark © (2004-09-22 16:44) [4]

Документирование и комментирование кода -- разные вещи.

← →
Mystic © (2004-09-22 16:53) [5]

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

← →
by © (2004-09-22 16:59) [6]

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

← →
Mystic © (2004-09-22 17:06) [7]

комментировать только алгоритм

Ну... имхо, алгоритм надо документировать отдельно. Потому как в некоторых случаях по 10-20 строчкам программы можно написать диссертацию... Да и текстовый файл не лучшая возможность для выражения ряда идей.

← →
Sandman25 © (2004-09-22 17:06) [8]

Длинные названия можно выбрать через Ctrl+пробел. Желание использовать краткие наименования часто объясняется незнанием Code Completion.

← →
iZEN © (2004-09-22 18:10) [9]

Пример "Структура кода": http://izen.dev.juga.ru/notebook/agreements/codestruct.html

← →
jack128 © (2004-09-22 18:16) [10]

iZEN © (22.09.04 18:10) [9]
Ну вот например

/*
* Возвращает записи экземпляра класса Properties, прочитанные из файла.
* В случае исключений ввода-вывода IOException и FileNotFoundException
* они передаются вызывающему коду.
* @param String путь к файлу.
* @return Properties записи свойств, прочитанные по URL.
* @throws IOException исключение ввода-вывода.
* @throws FileNotFoundException исключение файлового доступа.
*/
public Properties getProperties(String file) throws IOException, FileNotFoundException
В чем смысл этого комментария? Помоему и так из декларации понятно, что делает этот метод..

← →
DiamondShark © (2004-09-22 18:24) [11]

> В чем смысл этого комментария?

А чтобы JavaDoc мог собрать описания. Больше ни в чём.

← →
iZEN © (2004-09-22 18:31) [12]

/**jack128 © (22.09.04 18:16) [10]
В чем смысл этого комментария? Помоему и так из декларации понятно, что делает этот метод..
*/
JavaDoc представляет собой законченный help по API (аналог MSDN). Ниоткуда его нельзя получить кроме как из текста исходника.

Представьте себе, что исходников у Вас нет, только class-файлы в архиве и документация javadoc. Что Вы можете подумать, глядя на строчку: public Properties getProperties(String file) без сопутствующих комментариев?! Может этот метод возвращает свойства файла дисковой системы?! Так нет же в нормальном JavaDoc написано, что возвращает то, что внутри него записано в виде структуры "свойств", то есть содержимое файла.

Комментарии должны быть краткими и понятными.
В Java не приходится балансировать между документированием ДЛЯ РАЗРАБОТЧИКА и ДЛЯ JavaDoc - как правило, это одно и то же и в одном исходнике. Рутину оформления и генерации берут на себя средства разработки (JBuilder, Eclipse, IDEA, NetBeans, etc.).

← →
Cosinus © (2004-09-22 18:39) [13]

Я пишу так:
Шапка - Кто, что, зачем :)
Подшапка - через 2 пустые строки краткое(редко, но бывает, что не очень коротенько получается:) описание ВСЕХ функций, процедур и т.д.
В самом проекте ИНОГДА краткие комментарии к кускам кода.
У меня по идее все должно быть понятно из названия и самого кода, если не понятно, то см.подшапку.

← →
Mystic © (2004-09-22 19:39) [14]

На самом деле при разработке у меня чаще возникают такие задачи:

1) найти место, где происходит определенная операция
2) поиск метода, который выполняет то, что мне нужно
3) понять работу подсистемы во взаимосвязи

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

← →
Sergey_Masloff (2004-09-22 21:09) [15]

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

← →
вразлет © (2004-09-23 12:31) [16]

http://lbs.tik.net.ua/Documents/rus/Programming/Rules/CHAP3.html

← →
Mystic © (2004-09-23 12:44) [17]

Теперь другой вопрос --- кто эти коментарии читает?

← →
vecna © (2004-09-23 12:45) [18]

Sergey_Masloff
Это же бред! А если я сотру все шапочную историю? Или допишу кому-нить, чего-нить?

Системы контроля версий - единственное правильное решение
.

← →
Sergey_Masloff (2004-09-23 20:46) [19]

vecna © (23.09.04 12:45) [18]
1) Учимся читать. СКВ ес-сно применяется но она спасает совсем от другого. Ну видишь ты файл он изменялся 236 раз, знаешь когда и кто его изменял. Что дальше? Чем поможет?

2) Если сотрешь чего не свое - побеседуешь со службой внутренней безопасности. Желание пропадет надолго - гарантировано.

← →
KilkennyCat © (2004-09-23 23:36) [20]

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

← →
Гаврила © (2004-09-24 00:17) [21]

> [19] Sergey_Masloff (23.09.04 20:46)
> vecna © (23.09.04 12:45) [18]
> 1)Ну видишь ты файл он изменялся 236 раз,
> знаешь когда и кто его изменял. Что дальше? Чем поможет?

Добавлю, знаешь еще и ЧТО менял. И Можешь откатиться на любую предыдушую версию одним нажатием кнопки. И можешь посмотреть различия в коде между версиями в визуальной тузле.
А история изменений в юните - имхо, захламление кода. Кроме того, это дублирование информации, что есть, опять же, имхо, грубая ошибка.
Правильное решение - заставлять команду писать комментарии на версию при выполнении Check in

← →
Sergey_Masloff (2004-09-24 06:52) [22]

Гаврила © (24.09.04 00:17) [21]

>Добавлю, знаешь еще и ЧТО менял.
Не знаешь только самого главного - зачем ;-)
Не собираюсь переубеждать - в конце концов каждый вырабатывает для себя рано или поздно свои правила. Проекту с которым работаю сейчас я 8 лет, несколько миллионов строк кода и несколько (много) тысяч модулей. За те почти 4 года что я принимаю участие в этой разработке я достаточно четко убедился что модули имеющие в себе историю изменений и комментарии изменений в тексте (в VCS тоже комментарии есть но более крупных этапов, то есть одно другому не мешает) требуют для поддержки и изменения на порядок меньше усилий. Для меня это достаточное основание следовать такому стилю.

← →
Гаврила © (2004-09-24 10:22) [23]

> [22] Sergey_Masloff (24.09.04 06:52)

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

> ...требуют для поддержки и изменения на порядок меньше усилий

Поясни на примере ? каким именно образом, может, это я не прав ? Давай выясним истину :-)

← →
Sergey_Masloff (2004-09-24 10:45) [24]

Гаврила © (24.09.04 10:22) [23]
>Как это не знаешь, зачем ?
Ну так. Ты ж не один над проетом работаешь? Нет. Про некоторые модули даже в общем не знаешь ничего не то что подробности реализации.

>разницы в коментарии в коде и комментарии в системе контроля >версий с этой точки зрения нет никакой.
>с "VCS"
VCS это Version Control System так что я думаю с какой-то реинкарнацией ее работали все ;-)

>В конце концов ,когда мы смотрим на VCL, мы нигде не видим >никакой истории изменений
Как часто такие изменения в нее вносятся? В ту версию что стоит конкретно у тебя? ;-)

>Поясни на примере ?
Да не надо специальных примеров. Обнаружено неправильное поведение программы. Находится место в котором возникает ошибка. Тут же на месте видим что это изменил вася пупкин версия модуля XX поднимаемся в шапку видим что вася хотел добиться. И почему.
В 50% случаев понимаем что вася сделал правильно и это не ошибка а фича в остальных понимаем что он хотел сделать и почему не прав.
Времени уходит минимум по сравнению с анализом отчетов систем контроля версий. Особенно это касается микроизменений. Ну что ты напишешь в систему контроля версий если твое изменение - изменить пару бит в маске ;-)

← →
Гаврила © (2004-09-24 11:03) [25]

> Ну так. Ты ж не один над проетом работаешь?

Ну да. Поэтому и надо зааставлять всех держать в порядке именно свои модули

> VCS это Version Control System

Да ,я было подумал, что это название конкретного продукта :-)))

> Как часто такие изменения в нее вносятся? В ту версию что
> стоит конкретно у тебя? ;-)

Видимо, начиная с первой версии Delphi, изменений было внесено более чем достаточно

> Ну что ты напишешь в систему контроля версий если твое изменение
> - изменить пару бит в маске

Ну я напишу ,что изменил пару бит в маске, чтобы она типа правильно маскировала :-)
А ты видимо тоже самое напишешь в коде около объявления маски ?

Если я тебя правильно понял - преимущество твоего метода заключается в том, что у тебя комментарий привязан к конкретному месту в модуле, тогда как у меня он как бы на весь модуль, так ?

← →
Sergey_Masloff (2004-09-24 11:15) [26]

Гаврила © (24.09.04 11:03) [25]
>Поэтому и надо зааставлять всех держать в порядке именно свои >модули
ну у нас своих нет как правило... Кто последний правил того и модуль

>Видимо, начиная с первой версии Delphi, изменений было внесено >более чем достаточно
Ну перед распространением они причесывают ;-) Это раз. Да и релизы у них раз в полтора-два года а у нас каждый день по 20 штук ;-)

>А ты видимо тоже самое напишешь в коде около объявления маски ?
Ну, видимо да. Пример неудачный ;-)

Вобщем все наверное дело привычки.

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

← →
Гаврила © (2004-09-24 11:22) [27]

В общем, оба способа имеют по плюсу и по минусу
контроль версий
+ не захламляется код
- нет привязки к месту в модуле. Лечится обязательным указанием в комментарии на Check in названия метода \ процедуры - тогдаа искать будет проще("Like" в запросе).

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

← →
Cobalt © (2004-09-24 12:02) [28]

2 Гаврила © (24.09.04 11:22) [27]
Цитирую:
> И можешь посмотреть различия в коде между версиями в визуальной тузле.

Сразу видно, где менял.

А скажите лучше, как вы ведёте список задач, который вам/вы ставятся/ите

← →
Sergey_Masloff (2004-09-24 12:11) [29]

Cobalt © (24.09.04 12:02) [28]
Повторю. Уже сделано 100 изменений модуля. ЧТО сразу видно? Общего у модулей уже может быть только 50% текста. Или 30. Так что гладко было на бумаге...

>как вы ведёте список задач,
Самописная система. Интегрированая с системой учета рабочего времени (да и вообще все это в общую ИС интегрировано).

← →
Гаврила © (2004-09-24 12:11) [30]

> Cobalt © (24.09.04 12:02)

> Сразу видно, где менял.

Если пара сотен изменений, действительно не сразу видно

> А скажите лучше, как вы ведёте список задач, который вам/вы
> ставятся/ите

Мы используем Star Team
там сразу и контроль версий, и учет багов и список задач, и требования, все в одном флаконе

← →
Cobalt © (2004-09-24 14:41) [31]

> Sergey_Masloff (24.09.04 12:11) [29]

а пару сотен комментариев читать - это самое оно?

Мне кажется, что вопрос о сотне изменений - это из разряда гиперболы ;)

Кроме собственно комментариев в коде никто не ведёт документацию по технологии? Я имею в виду, что для каждого функционала описывается - как он работает в общем и его особенности. А подробнее - смотри код.

← →
Sergey_Masloff (2004-09-24 14:51) [32]

Cobalt © (24.09.04 14:41) [31]
>а пару сотен комментариев читать - это самое оно?
Читаешь 1 (один) комментарий - в месте ошибки. Потом поднимаешься наверх одним нажатием клавиши и смотришь общий комментарий на группу. Ну потом еще можно проверить остальные места связанные с этим изменением - ведь около каждого стоит меточка {VX.X-XXX}. Очень просто и удобно.

>Мне кажется, что вопрос о сотне изменений - это из разряда >гиперболы ;)
Нет. Это вполне реальная ситуация для более-менее долгоживущей системе. Я работаю с такими модулями ежедневно.

>Кроме собственно комментариев в коде никто не ведёт >документацию по технологии?
Нет.
1) На это никогда нет времени
2) Это все мгновенно устаревает
3) Как правило на каждый модуль из 1000 строк по технологии можно написать книжку на 200 страниц.

← →
КаПиБаРа © (2004-09-24 14:57) [33]

Sergey_Masloff (24.09.04 6:52) [22]
Не знаешь только самого главного - зачем ;-)
Ведите базу ошибок и доработок. Типа такой
1. Номер записи
2. Когда проявляется
3. Как проявляется
4. Кому поручено исправить
5. Кто исправил
6. Когда исправил
и т.д.

При исправлении в комментарии VCS добавляйте ссылку на номер записи в базе ошибок.

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

← →
Sergey_Masloff (2004-09-24 15:02) [34]

КаПиБаРа © (24.09.04 14:57) [33]
Почему думаешь что такой базы нет? И что толку было бы с такой базы если бы там не было ЧТО сделано для исправления. А то может там переустановили Windows васе пупкину все заработало.

Обнаружено неправильное поведение программы. Находится место в котором возникает ошибка. Тут же на месте видим что это изменил вася пупкин версия модуля XX поднимаемся в шапку видим что вася хотел добиться. И почему.
В 50% случаев понимаем что вася сделал правильно и это не ошибка а фича в остальных понимаем что он хотел сделать и почему не прав.
Времени уходит минимум по сравнению с анализом отчетов систем контроля версий. Особенно это касается микроизменений. Ну что ты напишешь в систему контроля версий если твое изменение - изменить пару бит в маске ;-)

Простите, не понял... у меня есть многокилометровая шапка, в коде обнаружилась ошибка... КАКИМ ОБРАЗОМ Я ПОЙМУ КТО И КОГДА ЭТУ ОШИБКУ СДЕЛАЛ ИСПОЛЬЗУЯ ШАПКУ? или вы коментируете каждый измененый байт?! =)

ЗЫ:
Не пойму как служба безопасности связана с модификацией кода.

← →
Sergey_Masloff (2004-09-24 15:22) [36]

vecna © (24.09.04 15:09) [35]
>Простите, не понял... у меня есть многокилометровая шапка,
Для достижения понимания нужно читать мессаджи оппонента не через строчку а полностью. Взгляд на мир изменится ;-)

Повторю еще раз
В шапке строка:
{VERSION V1.0-1234 10-OCT-2003 by sm Перевод на альтернативный интерфейс с XXX. СЗ№123 от XXX. Тут еще пара строк зачем это нужно. И ссылка на документ в системе регистрации задач который может быть многостраничным с картинками и звуковыми файлами с матами несчастных юзеров}

Все места в коде затронутые этим изменением помечаются как
{V1.0-1234} - одна строка
{V1.0-1234}
группа строк
{/V1.0-1234}

Поэтому найдя проблемное место поднимаемся к шапке (какая разница какого она объема - поднимаемся к КОНКРЕТНОМУ месту) читаем для чего сделано и имеем возможность БЫСТРО побежать все места связаные логически с проблемным. Очень удобно, серьезно.

← →
Abuzer (2004-09-24 15:29) [37]

А что за проект такой, где в день по 20 релизов? Просто интересно :)

← →
Sergey_Masloff (2004-09-24 15:43) [38]

Abuzer (24.09.04 15:29) [37]
Мы АСУ-шники. Автоматизирована вся деятельность крупного (www.ingos.ru) предприятия. Так что "релизы" дело частое.

← →
Sergey_Masloff (2004-09-24 15:43) [39]

2 Sergey_Masloff
А в этой базе, где у вас хранятся записи о задаче - не хранится ещё и комментарий - что именно (то есть, где) исправлено (и почему ;)?

← →
Sergey_Masloff (2004-09-24 17:25) [41]

Cobalt © (24.09.04 17:23) [40]
Как это представляешь себе? Я исправил в строке 120 символы с 7 по 12?
Все же лучше около строки кода написать ВОТ ОНО!

>Sergey_Masloff (24.09.04 17:25) [41]
Хм...
мне кажется, что проще всё-таки посмотреть разницу между версией фала, изменённого по задаче, и предыдущей.

А если хочется видеть все изменения по куче задач - так это, ИМХО, просто вопрос автоматизации.

Сергей, я бы не хотел работать в команде под Вашим руководством
Что не мещает нам встретиться
попить пива
Вы как ?

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

← →
Sergey_Masloff (2004-09-24 22:48) [45]

Гаврила © (24.09.04 22:30) [43]
А чего на вы? Попить пива... да я абстинент практически. Хотя если в небольших количествах... Вобщем вполне можно.

Под моим руководством не грозит - в моей "команде" на данный момент 1 человек кроме меня ;-) Ну в смысле это под моим руководством. Так то народу много. Но своей железной рукой я насаждаю свои взгляды только в небольшом сравнительно куске общего пиронга (проекта)

Гаврила © (24.09.04 22:30) [43]
Вот-вот. Работать никто не хочет, а вот по пиву, это мы как пионеры - всегда готовы!! :-)

> [46] jack128 © (24.09.04 22:50)

Почему же "работать никто не хочет" ? Одно другому не мешает, если разделено по времени

Sergey_Masloff (24.09.04 15:22) [36]
Именно это я и имел в виду, только без шапки в каждом модуле. Зачем шапка, когда ее полностью заменяет система регистрации задач.

Sergey_Masloff (24.09.04 22:48) [45]

> Но своей железной рукой я насаждаю свои взгляды только в
> небольшом сравнительно куске общего пирога (проекта)

:) До боли знакомая ситуация...

Документрирование и "дурно пахнущий код". Найти похожие ветки