Previous Entry Share Next Entry
несамодокументируемый код
arcflashsuit
poor_sysadm
Есть наверное только одна вещь, которую нельзя выразить в понятных именах функций и переменных, в красиво разложенных выражениях.
Теоремы, на которых строится код.
Не буду искать реальные примеры (чтоб не утонуть в нюансах какого-то хитрого алгоритма сортировки), но если у нас a>b, а c>a, то необходимости проверять, что c>b нет, и поэтому эту проверку мы опускаем - это не может прояснить (если читающий код с этой теоремой не знаком) ничто, кроме отсылки к этому утверждению (в данном случае это не то, чтобы теорема, a>b && b>c => a>с, но суть не меняется).
Собственно, код, где используются теоремы для незнакомых с ними непонятен абсолютно.

  • 1
С другой стороны, если не говорим о каких-то сложных математических расчетах, то такие вещи понятны на уровне бытовой логики.

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

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

> что с чем сравниваем, что из чего высчитываем

это должно быть понятно из названий переменных и описаний используемых структур

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

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

"Что с чем" - не в смысле "a и b", а одну физическую величину (например) с другой.

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

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

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

Пост-то о чём? Именно это и должно быть в комментариях.
"Бизнес-требования" закодить и не сохранить отсылку на документ с требованиями (с указанием авторства) - это вообще считай напрасно поработал.

Соглашусь. Поэтому я кроме комментирования кода стараюсь давать развернутое описание с примерами использования прямо в модуле кода. Ибо сопроводиловка бывает теряется, а модуль он как есть.
Писал недавно класс для чтения DBF FoxPro для последующей конвертации (ибо ODBC жрёт память как свинья помои), так прямо в комментариях расписывал структуру DBF/FPT с примерами, ибо задача почти разовая, а я сам потом забуду.

  • 1
?

Log in

No account? Create an account