Чужой код

← →
Anatoly Podgoretsky © (2005-10-29 12:19) [40]

Игорь Шевченко © (27.10.05 23:50) [35]
Если внутри длинного блока комментируется субблок, то этот субблок кандидат на осмвсленную процедуру, а комментарием станет ее название.
Комментировать, а точнее по смыслу описывать, стоит алгоритм блока и то если он нетривиальный.

← →
Igorek © (2005-10-29 15:49) [41]

> Игорь Шевченко © (27.10.05 23:50) [35]
> Igorek © (27.10.05 20:16) [32]
> 1) Это противоречащие друг другу критерии.

Интересно..
Критерий i противоречит критерию j, если i<>j ?

← →
BorisMor © (2005-10-30 00:11) [42]

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

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

← →
Игорь Шевченко © (2005-10-31 12:15) [43]

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

← →
SPeller © (2005-10-31 12:56) [44]

Игорь Шевченко © (31.10.05 12:15) [43]
Может быть, мы с таким не сталкивались :)

← →
_inic (2005-10-31 12:58) [45]

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

ЗЫ Короче зачем-то пережевал жёванное

← →
Джо © (2005-10-31 14:29) [46]

> [45] _inic (31.10.05 12:58)
> комментируя, например, функцию, мы не только передаем смысл
> ее действий (что часто можно выразить в названии), но и
> зависимость от других элементов программы, пределы значений,
> расшифровку возвращаемых значений и т.п.

1. Зависимость от других элементов программы должна быть сведена к 0.
2. Если таковая зависимость все-же существует, она должна быть недвусмысленным образом обозначена в самом коде:procedure ProcessUserData; begin Assert (Storage.User.YearOfBirth>=1990); ... end;
3. Пределы значений также можно явно обозначить через Assertion и заданием пользовательских типов данных:type TYear = 1990..3000;
или заменой типа данных классом со своей логикой обработки значений.

И комментарии при таком подходе совершенно излишни.

Ку? ;>

← →
Игорь Шевченко © (2005-10-31 14:34) [47]

Джо © (31.10.05 14:29) [46]

> И комментарии при таком подходе совершенно излишни.

В одной конторе, на вопрос: "А почему у вас комментариев в коде нету" был дан ответ: "Если кто сопрет, пусть помучается".

Вот как ты полагаешь, наверное, придумывать осмысленные имена для переменных, методов и классов стали довольно давно, однако, про необходимость комментариев почему-то пишут практически все гуру программирования. Им-то какой интерес ? :)

← →
isasa © (2005-10-31 14:47) [48]

придумывать осмысленные имена для переменных,
:)
Венгерская нотация

Ну а с VCL исходниками никто не работает?

← →
Igorek © (2005-10-31 14:47) [49]

Хватит спорить. Комментарии - зло. Точка. Это аксиома. Остальное вторично. Если без них туго - то это проблемы писаки.

← →
Джо © (2005-10-31 14:56) [50]

[47] Игорь Шевченко © (31.10.05 14:34)
> В одной конторе, на вопрос: "А почему у вас комментариев
> в коде нету" был дан ответ: "Если кто сопрет, пусть помучается".

Это, конечно, мощный аргумент :)

Я в своем посте утрировал слегка, разумеется. Просто достал вот такой код:var A: Integer; B: TDateTime; jkl: TClass1; ... // в B хранится дата рождения работника if B < 1989 then ...
Также достали дикие связи между юнитами, где практически каждый класс творит с другим, что ему пожелается и затем это все многословно комментируется в стиле: "Если в классе A поле B не инициализировано, то это работать не будет"...
Как по мне, в большинстве случаев достаточно комментария в виде "шапки" в модуле с описанием его назначения. Используемые нетривиальные алгоритмы тоже полезно комментировать (лично я, впрочем, предпочитаю в директории с проектом сохранять отдельные файлы .rtf с описание алгоритма, если нужно со схемой, а в коде даю ссылку на него. Придумал относительно недавно -- очень удобно). Ну, и еще полезно комментирование, если на его основе потом автоматически генерируется тех. докумментация. В общем, тезис: умеренность в комментариях, по моему, признак хорошо продуманного кода
Все имхо.

← →
Игорь Шевченко © (2005-10-31 15:05) [51]

isasa © (31.10.05 14:47) [48]

> Ну а с VCL исходниками никто не работает?

А вот представь, что у тебя vcl.hlp нету. И поработай.

Igorek © (31.10.05 14:47) [49]

Свою цитату сам вспомнишь ?

Джо © (31.10.05 14:56) [50]

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

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

← →
Igorek © (2005-10-31 15:11) [52]

> Свою цитату сам вспомнишь ?

Какую из? Фразу 2005 года? :)

← →
Игорь Шевченко © (2005-10-31 15:14) [53]

Igorek © (31.10.05 15:11) [52]

По-моему, 2004. "Грустно, до чего же ламерство окрепло" :)

← →
Igorek © (2005-10-31 15:24) [54]

> Игорь Шевченко © (31.10.05 15:14) [53]

Та дискуссия меня многому научила. :)
Я написал [49] полушутя, после обеда.. Дабы подогреть азарт.. Но если действительно принять [49], то много проясняется. Смысл в том, чтобы писать ясный код без комментариев до тех пор, пока это возможно. А не сразу добавлять простыни прозы. И только когда совсем невмоготу - написать маленький комментарий. Да и то.. часто вспоминать об этом случае потом и спрашивать себя "а нельзя было без комментариев".

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

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

мое имхо такое:
1. шапку модуля (классы, методы и пр.) нужно очень тчательно описывать:
а) семантику методов
б) семантику параметров
в) precondition, postcondition, ограничения
г) с недавших пор взял за моду писать как в java throws. Смысл, конечно не такой немоного - но хотя бы понятно, что вот такие исключения могут быть выброшены.
д) для классов пишу иногда примеры.

2. тело модуля нужно комментировать в расчете на опытного человека.
а) конечно нужно стараться придумывать вменяемые имена идентификаторов.
б) нужно комментировать тонкие элементы бизнес-логики: какой у системы ни будь дизайн от этого не уйти.
г) нужно разделить комантарии на оформительские и собсвенно комментарии. Да, классики говорят, что методы должны быть короткие. Но такое все же УДОБНО не всегда. Поэтому одним типом коментириев (у меня (**)) обозначаю части кода. Ну типа (* Инициализация данных по покупкам *). Другой вид комментирев (у меня //) можно использовать для пояснения логики.

← →
Dmitriy O (2005-10-31 16:18) [56]

Удалено модератором

Удалено модератором
Примечание: Offtopic

Честно говоря не могу понять людей, которые говорят, что комментарии излишни. То ли действительно с большими проектами не сталкивлись(>10 юнитов)... Вы вот говорите про хороший код. Это хорошо, когда код хороший(каламбур получился). В данном случае мне повезло с этим. Но ведь не всегда же вы будете разбираться в идеальном коде. Ну не всегда же программист ВСЕ знает. А с комментами проще разобраться, что эта процедура/функция делает.

1-ю задачу выполнил. :) Свою Bpl-ку сделал подгрузил к основному модулю Как мне сказали, что ближайшая наша работа будет - это написание вот таких модулей(для работы с БД), каждый из которых присоединяется к главному модулю.

> Честно говоря не могу понять людей, которые говорят, что
> комментарии излишни. То ли действительно с большими проектами
> не сталкивлись(>10 юнитов)...

В том то и дело, что сталкивались. И не колличеством юнитов меряется, а строк.

Чужой код Найти похожие ветки