Комментируете ли вы свои сорцы

← →
DrPass © (2006-10-28 01:00) [40]

> Суслик © (28.10.06 00:56) [38]

Два замечания:
а) Во-первых, не надо обижаться про "зарывание таланта", т.к. это абсолютно безобидная шутка. А на обиженных еще и воду возят.
б) Во-вторых, где ты в модулях VCL видел комментарии 8-)? И несмотря на их практически полное отсутствие, это не мешает замечательно читать исходники VCL

← →
Суслик © (2006-10-28 01:02) [41]

> Ketmar © (28.10.06 00:58) [39]
> >[38] Суслик(c) 28-Oct-2006, 00:56
> сколько читал генофонд -- вполне понимал. потому что написан
> вполне вменяемо и приятно.

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

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

← →
Суслик © (2006-10-28 01:05) [42]

блин, с начала весны не втягивался в пустые разговоры - а тут на те, втянулся :)

← →
DrPass © (2006-10-28 01:06) [43]

> Суслик © (28.10.06 01:02) [41]

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

← →
DrPass © (2006-10-28 01:07) [44]

> Суслик © (28.10.06 01:05) [42]

Это не пустые, это традиционный спор инженеров :)

← →
Суслик © (2006-10-28 01:11) [45]

> DrPass © (28.10.06 01:06) [43]

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

← →
DrPass © (2006-10-28 01:13) [46]

> о блин, за инженера меня уже принял.

А кто? Программист (даже с лирическими наклонностями) - это разновидность обычного инженера. Ладно, спокойной ночи :)

← →
Суслик © (2006-10-28 01:19) [47]

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

← →
Суслик © (2006-10-28 01:29) [48]

> DrPass © (28.10.06 01:13) [46]

а) раз ты однозначно программист и б) дабы получить практическую пользу от разговора объясни мне, пожалуйста, функционал метода (это из grids.pas - версия дельфи: 2006)

procedure TInplaceEdit.Invalidate;
var
Cur: TRect;
begin
ValidateRect(Handle, nil);
InvalidateRect(Handle, nil, True);
Windows.GetClientRect(Handle, Cur);
MapWindowPoints(Handle, Grid.Handle, Cur, 2);
ValidateRect(Grid.Handle, @Cur);
InvalidateRect(Grid.Handle, @Cur, False);
end;

← →
DrPass © (2006-10-28 01:40) [49]

> Суслик © (28.10.06 01:29) [48]

Вызываем перерисовку для "редактора" ячейки, потом получаем его размеры и вычисляем его положение на гриде, и перерисовываем этот участок грида. Это же чистый WinAPI. Его тоже нужно каментами снабжать - дескать, это у нас получить DC, это у нас открыть файл? Или все-таки не стоит MSDN Library копировать в код?

← →
Суслик © (2006-10-28 01:47) [50]

> DrPass © (28.10.06 01:40) [49]

все бы хорошо, но ты же не прав :)
ничего мы не перересовываем, мы только говорим, что нужно перерисовать при следующем WM_PAINT :) Спорить не буду (и цитировать не буду), почитай внимательно про ValidateRect и InvalidateRect.

(читай дальше, когда прочтешь msdn)
Ты можешь здесь без комментов понять, зачем сначала
ValidateRect(Handle, nil);
затем
InvalidateRect(Handle, nil, True);
?
Я нет.

← →
Суслик © (2006-10-28 02:10) [51]

> DrPass © (28.10.06 01:40) [49]

Понимаешь ли, здесь может быть зарыт глубочайший смысл, коего я не понимаю. Но я имею в доступности msdn. Читая его я не могу понять, что тут делается. Комменты имхо очень помогли бы.

← →
Ketmar © (2006-10-28 03:34) [52]

>[41] Суслик(c) 28-Oct-2006, 01:02
>почитай grids.pas.
вот это -- не читал.

>вот прямо и не знаю, хочется тыкнуть тебя куданить в этом исхонике
а где я написал, что читал весь генофонд? %-)

>[51] Суслик(c) 28-Oct-2006, 02:10
>Понимаешь ли, здесь может быть зарыт глубочайший смысл,
>коего я не понимаю.
сонный я вижу смысл в "недроблении" области прорисовки. дурацкий, правда. %-)
есть подозрение на рудименты 9x. %-)

← →
Чапаев © (2006-10-28 09:28) [53]

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

Эт лучше дневничок завести... Можно даже livejournal... ;-)

> почитай grids.pas.
> если через месяц ты сможешь мне объяснить как там все написано
> - пиво с меня.
Тю. Помнится, творил своего наследника TDbGrid. Перелопатил Grids & DbGrids. Заработало и без глубокого понимания "как там всё написано". ;-)

> Я, например, делал своих наследников TDataSet - для этого
> мне понадобилось просто почитать сурцы других датасетов.
Я, помнится, в подобной ситуации из демок TTextTable развивал до требуемой функциональности...

← →
TUser © (2006-10-28 09:53) [54]

Обычно значки свои ставлю в качестве комментариев

// :)
// :(
{!}

и т.д. Мне их смысл понятен.

← →
boriskb © (2006-10-28 10:05) [55]

Я учился на трудах Дейкстры
Например
http://blackbox.metasystems.ru/index.php?option=com_content&task=view&id=69&Itemid=15
и более ранних книгах

Поэтому всю жизнь комментировал.
Только надо помнить о пословице
"Заставь дурака богу молиться..."
:)

← →
boriskb © (2006-10-28 10:20) [56]

Не знакомым со стилем Дейкстры рекомендую его знаменитую притчу
http://2lib.ru/book/win/3586.html

Она не большая.

← →
Чапаев © (2006-10-28 10:31) [57]

> [56] boriskb © (28.10.06 10:20)
"Я рассказывал эту историю разным людям. Программистам, как правило, она нравилась, а их начальники обычно сердились все больше и больше по мере ее развития. Hастоящие математики, однако, не могли понять, в чем соль. "

Класс! ;-)

← →
Суслик © (2006-10-28 10:50) [58]

> Ketmar © (28.10.06 03:34) [52]
> сонный я вижу смысл в "недроблении" области прорисовки.
> дурацкий, правда. %-)
> есть подозрение на рудименты 9x. %-)

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

← →
DrPass © (2006-10-28 12:42) [59]

> Суслик ©

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

← →
Суслик © (2006-10-28 12:49) [60]

> DrPass © (28.10.06 12:42) [59]

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

← →
Real © (2006-10-28 12:50) [61]

> DrPass © (28.10.06 00:27) [25]

Приведенный пример с утрированным комментом, я бы оформил так:

var RecordCount: integer; begin // Сохраняем записи грида в файл FillDataFromGrid(Records); RecordCount:= CalcRecordsCount(Records); SaveToFile(Records, RecordCount); end;

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

← →
Anatoly Podgoretsky © (2006-10-28 12:51) [62]

А за инженера ответишь :-)

← →
Джо © (2006-10-28 12:56) [63]

> [61] Real © (28.10.06 12:50)
>
> > DrPass © (28.10.06 00:27) [25]
>
>
> Приведенный пример с утрированным комментом, я бы оформил
> так:
>
> var
> RecordCount: integer;
> begin
> // Сохраняем записи грида в файл
> FillDataFromGrid(Records);
> RecordCount:= CalcRecordsCount(Records);
> SaveToFile(Records, RecordCount);
> end;
>
> В последствии, просматривая код - достаточно прочитать одну
> строку комментария, чтобы узнать (не понять!) что делает
> этот блок. Никто не говорит что избыточные комментарии это
> хорошо. Но также плохо - полное их отсутствие. В любом деле
> нужно иметь чувство меры.

Подобный комментарий можно спокойно выкинуть и назвать метод SaveGridRecords. И не нужно комментария.

← →
Real © (2006-10-28 13:07) [64]

> Подобный комментарий можно спокойно выкинуть и назвать метод
> SaveGridRecords. И не нужно комментария.

Можно и так. Но дисскусия идет ведь не о хорошем тоне в наименовании сущностей, а комментировании. И потом, комментарий все таки выделяется в коде намного явственней чем имя процедуры. Согласен, такой комментарий, особенно учитывая размер процедуры вроде и не нужен, но тут больше дело принципа: если начать в каких то случаях комментировать, а в каких то нет - то рано или поздно комментариев будет становится все меньше и меньше. Я стараюсь не поощрять в себе тенденцию избегать комментарии где они вроде и не сильно нужны, чтобы придерживаться единого стиля всегда. Из тех же соображений - я никогда не оставляю имена типа Button1, Button2 и т.д. даже если этот бутон вызывает какое нить окошко с About :)

P.S. Разве что с TLabel исключение :) Их всегда оставляю как Label1, ну может кроме случаев когда на них висит обработчик

← →
Суслик © (2006-10-28 13:12) [65]

О ужас, я в последнее время стал вообще локальные переменные называть A, B, C и т.д. (в некоторых случаях есно).
Иногда суть переменно не описывается и 30 символами.
Иногда легче назвать коротко и привести описание.

> но тут больше дело принципа: если начать в каких то случаях
> комментировать, а в каких то нет - то рано или поздно комментариев
> будет становится все меньше и меньше. Я стараюсь не поощрять
> в себе тенденцию избегать комментарии где они вроде и не
> сильно нужны, чтобы придерживаться единого стиля всегда.
> Из тех же соображений - я никогда не оставляю имена типа
> Button1, Button2 и т.д. даже если этот бутон вызывает какое
> нить окошко с About :)
>
> P.S. Разве что с TLabel исключение :) Их всегда оставляю
> как Label1, ну может кроме случаев когда на них висит обработчик

А как же с принципами, сначала TLabel, потом смотришь, все больше и больше всяких XXX1
Принципы дело такое не укоснительно, иначе какие же оны принципы, только психологическая отговорка.

> [48] Суслик © (28.10.06 01:29)
> procedure TInplaceEdit.Invalidate;
> var
> Cur: TRect;
> begin
> ValidateRect(Handle, nil);
> InvalidateRect(Handle, nil, True);
> Windows.GetClientRect(Handle, Cur);
> MapWindowPoints(Handle, Grid.Handle, Cur, 2);
> ValidateRect(Grid.Handle, @Cur);
> InvalidateRect(Grid.Handle, @Cur, False);
> end;

а что тут непонятного? зачем повторение кода?
я конечно не программист но видно же, что сначало прорисовка главного окна, затем вычисление области прорисовки для клиента и сама прорисовка клиентка (ячейки)

> VirEx © (28.10.06 13:59) [67]

согласно msdn тут прорисовки нет. тут есть только обозначение областей, которые нужно прорисовать.

зачем сначала убирать регион из области прорисовки
ValidateRect(Handle, nil);
а затем добавлять
InvalidateRect(Handle, nil, True);

причем в обоих случаях регион одинаков - клиентский размер.

>[53] Чапаев(c) 28-Oct-2006, 09:28
>Эт лучше дневничок завести... Можно даже livejournal... ;-)
в жыжу я другим какаю. %-)
а мысли у меня часто в hostory.txt лежат. часто даже к проекту мало относящиеся. %-) недавно перечитывал history.txt от одной своей программы. нашёл фразу: "квадратная голова далеко не укатится". долго думал.

>[65] Суслик(c) 28-Oct-2006, 13:12
>локальные переменные называть A, B, C и т.д.
это нормально. за годы вырабатывается привычка именовать определённые переменные определённым образом. у меня вот есть старая привычка именовать переменные циклов как "f", "c", "z" (вместо обычных "i", "j", "k"). со Спекки осталась -- там "for" набиралось одним нажатием кнопочки "f". ну и -- не будешь же до "i" потом тянуться? %-) остальные тоже рядом. и ты пы.
кстати, привычка глупая, но приставучая. если правлю чужой код -- сначала все "i", "j", ... переименовываю "под себя". %-)

> А как же с принципами, сначала TLabel, потом смотришь, все
> больше и больше всяких XXX1
> Принципы дело такое не укоснительно, иначе какие же оны
> принципы, только психологическая отговорка.

Согласен на все сто :) И сначала старался именно так и поступать. Но потом отказался по той причине, что незачем переименовывать то, что по большому счету имеет отношение только к интерфейсу, а не к коду. А если лэйбл учавствует в коде - то обязательно переименовываю.

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

// Для определения точек разрыва длинной строки (верстка абзаца) решаем задачу динамического программирования (см. Software Practice and Expirience 11 (1981), 1119-1184) type TNelderOption = record Size: Cardinal; // Размер структуры (обязательно) Flags: Cardinal; // Флаги (обязательно) Func: TMathFunction; // Функция (обязательно) N: Integer; // Размерность (обязательно) X0: PExtended; // Указатель на начальную точку (обязательно) X: PExtended; // Указатель куда записывать результат (обязательно, может совпадать с X0) Eps: Extended; // Точность (опция FIND_MIN_USE_EPS) Delta: Extended; // Способ проверки (опция FIND_MIN_USE_DELTA) R: Extended; // Расстояние между вершинами симплекса (опция FIND_MIN_USE_R) Mode: Integer; // Метод решения (опция FIND_MIN_USE_MODE) Alpha: Extended; // Коэффициент отражения (опция FIND_MIN_USE_ALPHA) Beta: Extended; // Коэффициент сжатия (опция FIND_MIN_USE_BETA) Gamma: Extended; // Коэффициент растяжения (опция FIND_MIN_USE_GAMMA) end; ; =========================================================== ; Чтение EXE-файла ; =========================================================== @@ReadLoop: ; Читаем кластер PUSH AX CALL ReadCluster ; Коррекция на переполнение MOV AX, ES MOV CL, 4 SHR BX, CL ADD AX, BX MOV ES, AX XOR BX, BX POP AX ; Находим следующий кластер MOV DI, AX SHR DI, 1 PUSHF ADD DI, AX ADD DI, OFFSET FAT_TABLE MOV AX, [WORD DS:DI] POPF JC @@OddCluster AND AH, 0Fh JMP @@FindComplete @@OddCluster: MOV CL, 4 SHR AX, CL @@FindComplete: CMP AX, 0FF8h JL @@ReadLoop POP DX MOV DS, DX ; На текущий момент: ; CS [=0] ; ES:BX = Конец прочитанного EXE-файла ; CS:SI = SkipIP (поскольку идет сразу за ExeName) ; DS, DX = Сегмент, начало заголовка EXE-файл ; AX, CX, DI = ? ; BP = первой сектор второго кластера ; ===========================================================

> [68] Суслик © (28.10.06 14:17)
>
> > VirEx © (28.10.06 13:59) [67]
>
> согласно msdn тут прорисовки нет. тут есть только обозначение
> областей, которые нужно прорисовать.
>
> зачем сначала убирать регион из области прорисовки
> ValidateRect(Handle, nil);
> а затем добавлять
> InvalidateRect(Handle, nil, True);
>
> причем в обоих случаях регион одинаков - клиентский размер.

одинаковый?
ValidateRect(Handle, nil);
ValidateRect(Grid.Handle, @Cur);

> VirEx © (28.10.06 17:37) [72]

речь была про первые две строки, т.е. про

ValidateRect(Handle, nil); InvalidateRect(Handle, nil, True);

Очень редко...
обычно чтонить вроде того

// ОСТАНОВИЛСЯ ТУТ!!!!

или

// НЕ РАБОТАЕТ СОРТИРОВКА, ПРОВЕРИТЬ

и иногда в интерфейсах примерно так:

TDiscipline = class(TAdaptedObject)
private
FName:String;
FBalls:integer; // -1 если просто строка
FHoursCount:Integer;
...
end;

> Позвольте предположить, что вам просто лень писать комменты

Не лень, а жаба.
Практически любой ЯВУ довольно информативная и человекочитаемая вещь. Зачем тратить время на лишнюю работу? Лучше это время потратить на обдумывание как бы написать такой код, чтобы вообще не возникало необходимости его потом читать.

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

Комментируете ли вы свои сорцы Найти похожие ветки