Рекомендуемые правила оформления кода

[pu4koff]

Сообщение от Вадим Мошев

Разделительные комментарии. Служат для визуального разграничения блоков кода. Я только применял их для разделения меду собой подпрограмм или методов, хотя при написании дипломного проекта я делал более подробное деление:

Это всё от унылости IDE. Если взять Visual Studio + C#, то подпрограммы в один клик сворачиваются в одну строку с описанием (имя и параметры). Так же есть #region ... #endregion, которые позволяют делать то же самое, но вручную, т.е. можно уже несколько методов свернуть и вместо них будет краткий поясняющий комментарий.

Сообщение от Вадим Мошев

...
Procedure AnalyzeAndRate;
// Эта процедура выполняет анализ полученных ответов
// и ставит оценку по выбранной шкале
var
    RightAnswersCount, j: byte;

begin
    код процедуры
end;
...

Так не пойдёт. Если делфи научится (а может уже научилась в новых версиях) сворачивать блоки, то комментарий к функции окажется скрытым и чтобы его прочесть, придётся разворачивать весь код функции, что не есть правильно. Описание функции должно быть над её реализацией.

Сообщение от Вадим Мошев

Здесь я использую символ тире для отделения того места, где описываются типы, объявляются глобальные переменные и т.д.
Знак равенства я использую для отделения подпрограмм друг от друга.

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

Сообщение от Вадим Мошев

Замечу, что чётких правил выбора между однострочными и многострочными комментариями у меня не сформировалось, посему у меня такой комментарий может быть каким угодного – одно- или многострочным.

Лучше для таких целей использовать синтаксис однострочных комментариев, а многострочные оставить для "скрытия" участков кода от компилятора. Если же использовать многострочные комментарии, то каждую функцию/метод придётся "закомменчивать" отдельно.

Сообщение от Вадим Мошев

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

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

Сообщение от Вадим Мошев

Комментарий следует писать так, чтобы он казался своеобразным «заголовком» комментируемого куска кода, то есть самый первый символ комментария находился левее всех символов комментируемого куска кода.

Даже по этой логике, описание функции должно быть до слова function.

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

...
  // Показываем нужные элементы
  LabelTypeYourAnswer.Show;
  LabelTypeYourAnswer.Caption:=
    'Введите ответ с клавиатуры и нажмите кнопку ответить. ';

  If R.CaseSensitive then
  begin // а в таких случаях еще и блоки создавать, а иначе else теряется и структура ломается
    LabelTypeYourAnswer.Caption:=
      LabelTypeYourAnswer.Caption+ 'Регистр букв УЧИТЫВАЕТСЯ.'
  end
  else
  begin
    LabelTypeYourAnswer.Caption:=
      LabelTypeYourAnswer.Caption+ 'Регистр букв НЕ УЧИТЫВАЕТСЯ.';
  end;
...

Сообщение от Вадим Мошев

В некоторых случаях поясняющий комментарий может располагаться не сверху, а справа, и как бы «лежать» на некоторой строчке.

Считаю, что это уместно практически только в случаях типа:

if (a > 5)
...
else if (a > 2)
...
else // a <= 2
...

"Полноценные" комментарии частенько достаточно длинны, что приводит к горизонтальной прокрутке.

Сообщение от Вадим Мошев

Также такими комментариями я пользуюсь для того, чтобы описать поля какой-то записи:

type
	Student = record
			FullName: string; // ФИО студента
			Group: string; // Название группы, где он учится
			IsFined: // Флаг "отчисленности" студента, показывает, отчислен ли он
		  end;

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

[Arigato]

Сообщение от pu4koff

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

Если речь о Делфи, то там есть 2 типа многострочных комментариев: { ... } и (* ... *), так что проблемы закомментить кусок кода не будет.

[Вадим Мошев]

Arigato

Я такие конструкции пишу в 1 строку:
if ( s && s_own ) delete s;

А как при пошаговой трассировке узнаете, выполнилось ли у вас условие, или нет?
Лично я бы писал вот так

If (s && s_own)
	          delete s;
	
// вертиклаьные отспуты

// тут продолжаем писать код

И всё понятно, выполнилось условие или нет... Хотя я рассуждаю с позиции Delphi, мне на c/c++/c# ни разу не приходилось трассировать, но, думаю, там ничего не меняется...

[Utkin]

Сообщение от still_alive

Что мы видим при первом поверхностном осмотре:
1) неудачные имена переменных
2) выдвигаем предположение, что локальные переменные начинаются с маленькой буквы, а данные-члены класса с большой
3) магическое число 8
4) непонятные (ненужные) развертывания циклов
5) шаманство с переменной длины, это можно сделать красивее
6) ненужные проверки типа true = true (if flag[i] = true вместо if flag[i])
7) я понимаю, что дельфи регистронезависим, но придерживаться одного стиля надо все-таки
8) проверка с 8 внутри цикла - есть подозрение, что можно вынести
9) exit - затрудняет читабельность, так как приходится искать или думать, чему же в этот момент равно result
10) большое кол-во exit в разных местах кода напрягает
11) два if можно менять на один

Примено так. На основании 4, 5, 8, 10, 11 можно выдвинуть предположение, что код скорее всего нуждается в кардинальных изменениях (а здесь это почти переписывание, так как конечный код очень мало будет схож с текущим).

Я это имел в виду. Но поскольку я тогда проделал это за минуту примерно, то звиняйте если что

Читаем Ваши пункты: неудачные, предположение, непонятные (кстати не эквиваленто слову ненужные), красивее, if flag[i] = true вместо if flag[i] - этот аргумент вообще меня убил. Однозначно из-за этого нужно все переписать, да. Дальше - подозрение, напрягает. Иными словами большинство пунктов откровенные придирки. Далее Вы упорно игнорируете автозамену. Мне про это в каждом посте писать что ли? Еще раз - есть АВТОЗАМЕНА. Как Вам объяснить? Пункт в меню Правка обычно... Объясните мне почему Вы игнорируете ее? Честно пока увидел только эмоции и только один вопрос меня по настоящему заинтересовал. А почему Вас 8-ка не устроила?
Да Вы читали книги, но не можете проявить инициативу, подумать самостоятельно. Та же автозамена - 5 постов подряд одно и тоже из пустого в порожнее. Почему? Потому что в книгах не пишут про банальную автозамену имен переменных . У Вас в шаблоне не предусмотрена автозамена. Я не могу достучаться до Вас и обяснить, что есть механизмы отличные от Ваших представлений.

[Arigato]

Вообще, крайне редко трассировкой пользуюсь. Но даже если и придется, то зашли мы по ветке if или нет имеет смысл знать, когда у нас там более 1 оператора. А тут и так все понятно.

[Rififi]

Я такие конструкции пишу в 1 строку:
if ( s && s_own ) delete s;

[Alex11223]

Если делфи научится (а может уже научилась в новых версиях) сворачивать блоки

Не знаю насчет новых версий, но для всех Дельфи и Билдеров, начиная с ранних версий, есть CnPack + Geexpert.

[Arigato]

Сообщение от Rififi

Я такие конструкции пишу в 1 строку:
if ( s && s_own ) delete s;

А в чем проблема с отладкой? Вот, поясни...

[Вадим Мошев]

Можно я за него поясню? Я ведь уже говорил о проведении пошаговой трассировки. Вот у вас выделена эта строчка. Вот вы делаете следующий шаг. И непонятно, выполнилось ли у вас условие или нет. А вот при такой записи:

if ( s && s_own )
	 delete s;

Это будет видно хорошо. То есть, если "строка выполнения" перескочила тело условного оператора, то условие не выполнилось.

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

[Пепел Феникса]

а чтобы узнать значения операндов, надо крутить далеко вверх

при отладке как бы не нужно никуда крутить.