Правила оформелния кода, названия компонентов

← →
без ника (2006-03-17 14:48) [0]

Хочется узнать какие есть правила оформления кода в Delphi (ну и не только в нем). Может у кого есть корпоративная документация по этому поводу? Интересует:

1) Название компоненет TButton1 - TBtOk - TButonOk - TbtnOk
2) Как правильно писать описание к процедурам, классам.
3) Названия для локальных переменных, private переменных и т.д.
4) Названия модулей проектов.

Буду рад любой информации. Если есть документация с радостью приму на dima_1st@mail.ru

← →
Джо © (2006-03-17 14:48) [1]

Смотри исходные тексты VCL.

← →
Джо © (2006-03-17 14:49) [2]

Ну, или вот:
http://delphi.about.com/gi/dynamic/offsite.htm?zi=1/XJ&sdn=delphi&zu=http%3A%2F%2Fcommunity.borland.com%2Farticle%2F0%2C1410%2C10280%2C00.html

← →
без ника (2006-03-17 14:56) [3]

Хотелось бы увидеть документацию существующей компании... Знаю, что в некоторых компаниях такие документы есть.

← →
Leonid Troyanovsky © (2006-03-17 15:09) [4]

> без ника (17.03.06 14:56) [3]

> Хотелось бы увидеть документацию существующей компании..
> . Знаю, что в некоторых компаниях такие документы есть.

Пал Андреич, Вы - шпион?

--
Regards, LVT.

← →
без ника (2006-03-17 15:25) [5]

Нет не шпион :) Думал это не настолько секретная информация чтоб ею не поделиться ...

Просто теория хороша, а в компании обычно документация проверена ПРАКТИКОЙ реальных проектов - и не по одному году. Вот по этому и прошу документацию от реальных фирм.

← →
Leonid Troyanovsky © (2006-03-17 15:28) [6]

> Джо © (17.03.06 14:49) [2]
> Ну, или вот:

Вот - уже лучше.
Правда, есть одна непоследовательность: признается правильным
if () then DoSomething;
а c блоком
if () then begin .. end;
хотя должно было бы
if () then begin .. end;
или полностью
if () then begin .. end else begin .. end;
Интересно, что на это когда-то обратил внимание один сишник,
разглядывая исходники VCL.
Я, в общем-то, с ним согласился и пользую это правило
и для while () do, for .. do, etc.
Ну а блоки try..end делаю подобно begin..end (кто-то тут недавно
интересовался), тогда, собс-но, легко видеть, какой end
чего закрывает.

--
Regards, LVT.

← →
Eraser © (2006-03-17 15:31) [7]

> без ника (17.03.06 14:48)

http://www.delphikingdom.com/asp/viewitem.asp?catalogid=802

← →
Сергей М. © (2006-03-17 15:31) [8]

> без ника (17.03.06 15:25) [5]

Нет никакой документации на эту тему.
А есть Паскаль (на него есть "документация").
И есть так же стиль оформления текстов юнитов, принятых Борландом (отступы, пробелы-табуляции, комменты и т.д. и т.п.).
Есть так же принципы именования символьных идентификаторов (символьные ид-ры типов начинаются с литеры "T", от слова Type).

Можно сколь угодно спорить о целесообразности введения Борландом таких "норм", но тогда и речь о "правилах оформления кода" в Делфи-программах вряд ли имеет какой-либо смысл.

← →
Leonid Troyanovsky © (2006-03-17 15:34) [9]

> Leonid Troyanovsky © (17.03.06 15:28) [6]

> хотя должно было бы

Млин, корявая илюстрация получилась, нужные пробелы
проглотил сервер.
Имелось ввиду, что если уж после then начинать с
новой строки с двумя пробелами, то и в случае с
begin..end это тоже надо делать.

--
Regards, LVT.

← →
Игорь Шевченко © (2006-03-17 15:39) [10]

Сколько людей, столько и мнений.

Лично я давным давно пишу в стиле "Керниган-Ричи" (просьба не пинать, сам запинаю)

if (foo) then begin .... end else begin ... end; while (foo) do begin ... end;

← →
Германн © (2006-03-17 15:42) [11]

> Игорь Шевченко © (17.03.06 15:39) [10]
>
> Сколько людей, столько и мнений.
>
> Лично я давным давно пишу в стиле "Керниган-Ричи"

Я тоже всегда так писАл, но про стиль "Керниган-Ричи" первый раз слышу. :-)

← →
Eraser © (2006-03-17 15:50) [12]

А вот кто как оформляет оператор case итересно, особенно в ложной его форме? вот такая правокация )

> Игорь Шевченко © (17.03.06 15:39) [10]

недавно изучал вашу статью по Named Pipes, ещё тогда вспомнил "добрым" словом это оформление кода )) мягко говоря, непривычно ;-)

зы За статью с примером спасибо - помогла.

← →
Eraser © (2006-03-17 15:51) [13]

> Eraser © (17.03.06 15:50) [12]

> ложной его форме

сложной ))

← →
Leonid Troyanovsky © (2006-03-17 15:51) [14]

> Игорь Шевченко © (17.03.06 15:39) [10]

> Лично я давным давно пишу в стиле "Керниган-Ричи" (просьба
> не пинать, сам запинаю)

Дык, кого нельзя пинать Кернигана или Ричи?

Я ж не зря помянул сишника, ведь если сначала так:

if (polySmooth)
glClear (GL_COLOR_BUFFER_BIT);
else
glClear (GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);

а потом так:

if (polySmooth) {
}
else {
}

то получается нескладно.

Ведь, я ж начал с того, что если уж писать всегда с новой строки.

--
Regards, LVT.

← →
Германн © (2006-03-17 15:56) [15]

> Eraser © (17.03.06 15:50) [12]
>
> А вот кто как оформляет оператор case итересно, особенно
> в ложной его форме? вот такая правокация )

Лично я вот так:
case Integer of 1 : begin ... end; 2 : begin ... end; else begin ... end end;

← →
Германн © (2006-03-17 15:59) [16]

Токмо вот отступы всегда 2 пробела. В [15] почему-то не получилось.

← →
Leonid Troyanovsky © (2006-03-17 16:01) [17]

> Eraser © (17.03.06 15:50) [12]
> А вот кто как оформляет оператор case итересно, особенно
> в ложной его форме? вот такая правокация )

Квотирую, дабы не исказить кол-во пробелов:

> case (x) of > 1: > begin > ; > end; > 2: > DoSomething; > else > begin > ; > end; > end;

--
Regards, LVT.

← →
Eraser © (2006-03-17 16:02) [18]

мой вариант:
case x of 1: begin end; 2: begin end; // двойной отступ ;-( end;
всегда не давала покоя двойная табуляция между последними end"ами ))

← →
Leonid Troyanovsky © (2006-03-17 16:05) [19]

> Германн © (17.03.06 15:56) [15]

> 1 : begin
..
> else
> begin

Нескладушки :) Тогда уж else begin в одну строчку.

Т.е., если есть правило, то оно должно быть простым,
и применяться всегда.

--
Regards, LVT.

← →
Игорь Шевченко © (2006-03-17 16:08) [20]

> А вот кто как оформляет оператор case итересно, особенно
> в ложной его форме? вот такая правокация

case foo of 1: smth 2: begin smth end; 3: begin ... end; else begin .. end; end;

Leonid Troyanovsky © (17.03.06 15:51) [14]

> то получается нескладно.

Я бы не сказал, что нескладно, наоборот, операторные скобки при восприятии текста программы являются лишним шумом и отводить под них лишнюю строку мне кажется неудобным.
То есть, должно быть видно, какая часть кода выполняется при истинном условии и при ложном, а смотреть еще и на скобки (или на begin...end) вроде как незачем.

← →
Leonid Troyanovsky © (2006-03-17 16:13) [21]

> Eraser © (17.03.06 16:02) [18]

> всегда не давала покоя двойная табуляция между последними
> end"ами ))

Дык, нормально. Последний end виден хорошо.

--
Regards, LVT.

← →
Leonid Troyanovsky © (2006-03-17 16:27) [22]

> Игорь Шевченко © (17.03.06 16:08) [20]

> 1: smth
> 2:
> begin

Хе-хе, тоже попался ;)

В моем же случае, я всегда перехожу на новую строку,
затем два пробела, далее прикидываю, уложусь я
в одну строку и если нет, то пишу be^J (code insight),
который вставляет блок

> begin
> |
> end;

в нужное место.

--
Regards, LVT.

← →
Leonid Troyanovsky © (2006-03-17 16:34) [23]

> Игорь Шевченко © (17.03.06 16:08) [20]

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

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

--
Regards, LVT.

← →
Игорь Шевченко © (2006-03-17 16:50) [24]

Leonid Troyanovsky © (17.03.06 16:34) [23]

> Хе-хе, тоже попался ;)
>
> В моем же случае, я всегда перехожу на новую строку,
> затем два пробела, далее прикидываю, уложусь я
> в одну строку

То есть, ты пишешь

case foo of 1: bar1; 2: bar2; 3: begin bar3; bar31; .. end; end;

Я верно понимаю ?

> Но, их правильное использование помогает
> придать конструкции некую законченную форму, один взгляд
> на
> которую позволит найти в ней скрытые деффекты, например,
>
> тот же пропущенный end.

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

Например, мне было бы неудобно читать свой код вида:

if InterlockedIncrement(FSharedInfo^.LockCount) = 1 then begin FSharedInfo^.ThreadId := ThreadId; FSharedInfo^.RecursionCount := 1; end else begin if FSharedInfo^.ThreadId = ThreadId then begin Inc(FSharedInfo^.RecursionCount) end else begin FEvent.WaitForever; FSharedInfo^.ThreadId := ThreadId; FSharedInfo^.RecursionCount := 1; end; end;

слишком много строк и выделенные жирным зарезервированные слова отвлекают в сочетаниях
end
else
begin

Но тем не менее, читаю. Хотя сам так не пишу.

← →
Eraser © (2006-03-17 16:54) [25]

> Игорь Шевченко © (17.03.06 16:50) [24]

а как же работа в команде? Там нужен единый стандарт, которым де-факто является стандарт принятый в VCL.

← →
Игорь Шевченко © (2006-03-17 17:00) [26]

Eraser © (17.03.06 16:54) [25]

> а как же работа в команде? Там нужен единый стандарт, которым
> де-факто является стандарт принятый в VCL.

Отчасти да. Но важен именно единый стандарт, а не конкретный единый. Кроме того, я до знакомства VCL успел поработать в команде, где писали в стиле K&R, разумеется, на С и доводы в пользу этого стандарта мне кажутся достаточно убедительными, а главное, объективными.

Например, мне трудно, согласно стилю VCL, отлаживать конструкции вида

if foo then bar;

потому что ставя breakpoint на такую строчку (без дополнительного намаза) я всегда при выполнении попадаю на if, а мне хочется попасть на функцию bar, следовательно, я буду писать

if foo then
bar;

← →
Германн © (2006-03-17 17:01) [27]

> Нескладушки :) Тогда уж else begin в одну строчку.
>
> Т.е., если есть правило, то оно должно быть простым,
> и применяться всегда.

Так и есть. Очепятался. :(

← →
Германн © (2006-03-17 17:06) [28]

Точнее так:
case Integer of 1 : begin ... end; 2 : begin ... end; else ... end;

← →
Leonid Troyanovsky © (2006-03-17 17:07) [29]

> Игорь Шевченко © (17.03.06 16:50) [24]

> Я верно понимаю ?

Примерно так. Мне даже удалось нечто похожее изобразить в [17].

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

Дык, если придерживаться правил. А мне удалось заметить,
что стронники КР чаще их нарушают :)
Например, переносят на другую строку begin (или {).
Возможно, что это другое правило, но оно не звучит явно.
В любом случае, цельное правило уже будет сложней.

> слишком много строк и выделенные жирным зарезервированные
> слова отвлекают в сочетаниях
> end
> else
> begin

Возможно, потому, что begin в новой строке без отступа в 2 пробела.
Т.е., на что я и хотел обратить внимание дельфиской общественности.

> Но тем не менее, читаю. Хотя сам так не пишу.

Ну, это еще не самый худший образчик нашего чтива :)

--
Regards, LVT.

← →
Eraser © (2006-03-17 17:07) [30]

> Игорь Шевченко © (17.03.06 17:00) [26]

> Например, мне трудно, согласно стилю VCL, отлаживать конструкции
> вида
>
> if foo then bar;
........

вот с этим согласен, потому и применяю не VCL, JEDI стиль
см. Джо © (17.03.06 14:49) [2], Eraser © (17.03.06 15:31) [7]
который почти не отличается от VCL, пояснения к конструкции, которую вы упамянули там такие:
If statements should always appear on at least two lines. Example: // INCORRECT if A < B then DoSomething; // CORRECT if A < B then DoSomething;

← →
Игорь Шевченко © (2006-03-17 17:12) [31]

Leonid Troyanovsky © (17.03.06 17:07) [29]

> А мне удалось заметить,
> что стронники КР чаще их нарушают :)
> Например, переносят на другую строку begin (или {).

А если строка длинная, то как же ее не перенести ? :)

> Возможно, потому, что begin в новой строке без отступа в
> 2 пробела

То есть, ты предлагаешь так?

if foo then begin smth; ..... end else begin smth_another; .... end;

?

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

← →
Leonid Troyanovsky © (2006-03-17 17:38) [32]

> Игорь Шевченко © (17.03.06 17:12) [31]

> А если строка длинная, то как же ее не перенести ? :)

Ну, в твоем примере она не особо длинная:

> 1: smth
> 2:
> begin
> smth
> end;

а begin - с новой строки ;)

> То есть, ты предлагаешь так?

> if foo then
> begin
> smth;
> .....
> end

> Как-то на мой взгляд не очень воспринимается...

Тут есть одна маленькая тонкость - у тебя отступ в 3 пробела.
Поэтому, оно и не очень смотрится. Кроме того, мы должны
быть готовы к тому, что и само foo будет более громоздким:

> > if (foo1 ..........) and > (foo2...........) and > (foo3...........) then > begin > ; > end > else > begin > ; > end; >
Но, тут уж ничего не поделаешь. Хотя, отступ даже в один пробел
тут вполне заметен.

--
Regards, LVT.

← →
Игорь Шевченко © (2006-03-17 17:42) [33]

Leonid Troyanovsky © (17.03.06 17:38) [32]

> Ну, в твоем примере она не особо длинная:

Так короткие и не переносят те самые поклонники K&R, которых ты упоминал :)

> Тут есть одна маленькая тонкость - у тебя отступ в 3 пробела.

Вообще-то четыре :) Я специально набил так, зная, что скрипт форума пробел ест, не в количестве пробелов дело, а в стиле оформления.

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

← →
Leonid Troyanovsky © (2006-03-17 17:57) [34]

> Игорь Шевченко © (17.03.06 17:42) [33]

> Так короткие и не переносят те самые поклонники K&R, которых
> ты упоминал :)

Они не должны переносить { :)
Т.е., д.б.

2: begin
smth
end;

> Вообще-то четыре :) Я специально набил так, зная, что скрипт
> форума пробел ест, не в количестве пробелов дело, а в стиле

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

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

Я б еще добавил, чем проще правила, тем проще их применить.
Т.е., при минимуме обучения - приемлемый результат.

--
Regards, LVT.

← →
DelphiLexx © (2006-03-17 18:07) [35]

> Хочется узнать какие есть правила оформления кода в Delphi
> (ну и не только в нем). Может у кого есть корпоративная
> документация по этому поводу? Интересует:

Воспользуйся пакетом GExpert. Легко интегрируется в IDE Delphi т.е. после установки GExpert"a в Delphi появляется новое меню GExpert - которое имеет много наворотов один из которых форматирования текущего unit"a нажимаешь Ctrl+Alt+F и всё - unit отформатирован просто прекрасно.

← →
Eraser © (2006-03-17 18:12) [36]

> DelphiLexx © (17.03.06 18:07) [35]

можно, а ещё есть DelFor и масса других схожих утилит..
вот только тут не всех устраиватет как они форматируют код ;-))

← →
Джо © (2006-03-17 18:23) [37]

Ух, как много тут вариантов, оказывается, всего и не прочитаешь. :) Отвечу только на
> [9] Leonid Troyanovsky © (17.03.06 15:34)

А я отступы в блоках не множу, т.е., пишу так:
if () then ...
но, тем не менее, так:
if () then begin ... end;
Отступы везде в 2 пробела.

← →
без ника (2006-03-17 18:30) [38]

Осатлся не понятным вопрос по именованию визуальных констролов :

TBitBtn1, TButton1 - не так же оставлять ?

Я обычно делаю так :

TButtonMetodName TBitBtnDoSome

Хотя ADOStoperdProc - сокращаю до ADOSP_.....

Как правелььно поступать тут ???

> Джо © (17.03.06 18:23) [37]

> А я отступы в блоках не множу, т.е., пишу так:

Зря. Чего тебе двух пробелов жалко? :)
Ты, видимо, еще не все дочитал.

--
Regards, LVT.

> [39] Leonid Troyanovsky © (17.03.06 18:31)

Сижу пока читаю. Много разных вариантов.

Вот по поводу того, что тут назвали стилем K&R: мне лично кажется очень ненаглядным ("все в кучу", слишком "плотно", если можно так выразиться) этот способ.

Насчет непоследовательности "моего" стиля — согласен. Тем более, что в case делаю исключение: перед операторными скобками ставлю даблспейс. Но, привычка — вторая натура... :)

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

> [38] без ника (17.03.06 18:30)
> Осатлся не понятным вопрос по именованию визуальных констролов
> :
>
> TBitBtn1, TButton1 - не так же оставлять ?
>
> Я обычно делаю так :
>
> TButtonMetodName TBitBtnDoSome
>
> Хотя ADOStoperdProc - сокращаю до ADOSP_.....
>
> Как правелььно поступать тут ???

Лично я именую так:
btnOK, btnCancel, lbUserName (TLabel), edUserName (TEdit) и т.д.

> Джо © (17.03.06 18:43) [41]

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

> Джо © (17.03.06 18:41) [40]

> Вот по поводу того, что тут назвали стилем K&R: мне лично
> кажется очень ненаглядным ("все в кучу", слишком "плотно",
> если можно так выразиться) этот способ.

Компактность - тяжелое наследие Си.
Они ж там каждый байт экономили, бо качали исходники
через модем.

> Насчет непоследовательности "моего" стиля — согласен. Тем
> более, что в case делаю исключение: перед операторными скобками
> ставлю даблспейс. Но, привычка — вторая натура... :)

Вот. А вот если б сразу втянулся - было б и последовательней.

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

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

--
Regards, LVT.

> Джо © (17.03.06 18:43) [41]

> btnOK, btnCancel, lbUserName (TLabel), edUserName (TEdit)

Учился, видимо, по Ray Konopka.

--
Regards, LVT.

> [43] Leonid Troyanovsky © (17.03.06 18:55)

Да, в общем, согласен с доводами.

> [44] Leonid Troyanovsky © (17.03.06 18:57)

Не помню уже, у кого подсмотрел. Но только не у Конопки, его я точно не читал, просматривал просто (бумажной книги в свое время не имел).

У каждого программиста есть свой подчерк.
В своё время у меня он был очень ярко выраженый.
Но по мере развития он всё ближе приближается к стандартам VCL.
Но нет-нет да и VCL-исходники начинаю править под свой стиль (по ошибке).
Не откажу себе в удовольствии оствить образцы почерка.
if a then b else c; if a then begin b; end else begin c; end; case a of 1: begin b; end; 2: begin c; end; end; a:=b;
Отступы одинарные, минимум пробелов в выражениях (осталось от Паскаля)
begin либо у левого края, либо последний в строке, end под if, do, while и т.д. (больше текста умещается в маленьком окне редактора). При таком оформлении поиск потеряных begin"ов проиходит от конца файла.
Одно время пришлось писать очень длиные формулы в несколько строк.
Чтобы быстрее находить начала формул стал их записывать в таком виде:
a:=x+y+z +b-v -c+d; b:=z+x+y -a+v +c-d;
Такая запись результат плотного почерка. Эту идею я перенёс на большие константы - массивы строк. Результат
a:=("b" ,"c" ,"d");
Большие формулы больше не встречаются, писать запятую в начале строки не привык, а вот привычка писать if then else друг под другом сохранилась.

begin добавляй один пробел end

← →
Sergey Masloff (2006-03-17 22:27) [49]

Я лично для себя "усовершенствовал" метод Игоря (а оказывается и Кернигана)
begin всегда с новой строки если перед ним в строке нет else
if (foo) then begin .... end else begin ... end; while (foo) do begin ... end;

По case пишу только так:
Точнее так: case x of 1 : DoSmthng(); 2 : DoSmthng2(); 3 : DoSmthng3(); else ... end;
то есть в кейсе бегинов с эндами НЕТ
если нужно пишу так
if () then begin ... end else if () then begin ... end else begin ... end;

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

← →
Sergey Masloff (2006-03-17 22:28) [50]

Да в case отступ не показал. А он есть как обычно 2 символа

> без ника (17.03.06 14:48)
>
> Хочется узнать какие есть правила оформления кода в Delphi
> (ну и не только в нем).

Ну если "и не только в нём", то получи:

procedure Data3; begin adr:=alfa;bdc; wrc:=$85;w;wrd:=a3;w;wrd:=a2;w;wrd:=46;w;wrd:=a1;w;wrd:=a0; ... end;

А правила в примере гораздо более жёсткие, чем в Дельфи!

Мне кажется все-таки нужно учитывать содержание:
простые и однотипные по смыслу операторы записываю
как можно сжато по нескольку на строке чтоб меньше выделялись и не мешали
зато чем сложнее участок тем больше делаю выделение операторов
и на отдельных строках и даже между пустых строк
и когда разбираюсь постоянно форматирую и свой код и чужой
пока не будет ясности и всем советую если непонятна чужая программы
не стесняйтесь ее ковырять хотя бы пустыми строками

Leonid Troyanovsky © (17.03.06 17:57) [34]

> Они не должны переносить { :)
> Т.е., д.б.
>
> 2: begin
> smth
> end;

Видишь ли, операторные скобки в case - это специфика паскаля :) Лично мне begin на одной строке с выражением case кажется громоздким.

> Я б еще добавил, чем проще правила, тем проще их применить.
>
> Т.е., при минимуме обучения - приемлемый результат.

Да собственно, стандарты K&R и Borland по сложности практически не отличаются, разница в стиле, а набор правил почти одинаковый.

Правила оформелния кода, названия компонентов Найти похожие ветки