Подробнее о оформлении модуля

Давайте вернёмся к тексту программы Hello.odc:

MODULE TestHello;
(* это первая программа на языке
Компонентный Паскаль. Она ничего
толком не делает, кроме вывода строки
"Привет, мир!" *)
	IMPORT Log, Math;


	PROCEDURE Start*;
		VAR
	BEGIN
		Log.String('Привет, мир!'); (*Вывод строки в Рабочий журнал(Log)*)
		Log.Ln (*Переход на новую строку*)
	END Start;

BEGIN
END TestHello.

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

Заглавные буквы

В Компонентном Паскале заглавные буквы используются только для ключевых слов. Ключевые слова изменить нельзя. Они определены создателями языка, разнообразие их достаточно и исчерпывающе. В других языках, таких как Си или python заглавные буквы используются для обозначения констант. Впрочем, и в Компонентном Паскале никто не запрещает использовать заглавные буквы для констант. Но так не принято.

Точка с запятой

Это важная синтаксическая единица языка. Точно также точка с запятой есть во всех вариантах Паскаля и множестве других языков. В правописании точка с запятой используются для перечислений. Можно сказать, что и в КП она играет такую же роль. Но точку с запятой (дилиметер или терминатор (суть одно и тоже) -- разделитель) ставить всегда вовсе не обязательно. Есть три таких случая:

Не ставят после ключевых слов: IMPORT, TYPE, VAR, BEGIN -- после этих ключевых слов может ничего не идти, но как правило, идёт. Если поставить сразу точку с запятой, то будет считаться, что секция программы либо ничего не содержит, либо содержит пустую инструкцию.
Не ставят точку с запятой перед ключевым словом END. А зачем? Если есть ключевое слово END -- и так понятно, что дальше ничего нет.
После последнего END ставится точка, а не точка с запятой. Это особый случай, когда идёт указание КП ,что текст модуля закончен. Именно поэтому программисту разрешается после текста вставить КОММАНДЕР (и вообще всё что душе угодно), и КП не посчитает это за ошибку (на рисунке слева успешно скомпилированный модуль). Эта особенность позволяет хранить вместе с кодом и описание модуля, какие-то заметки, рекомендации и т. д., при этом не перегружая и не размазывая код между обильными комментариями.

Типичная ошибка при использовании точки с запятой

Заключается она в том, что этой самой точки с запятой попросту нет. Вот тут КП откажется компилировать текст, но не бросит программиста, а подскажет место, где он ошибку обнаружил:

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

Не правда ли, очень удобно? В ходе разработки программ на КП многие программисты определяют свои коды ошибок, они с таким же успехом отображаются в виде серых перечёркнутых квадратов. Сколько будет ошибок -- столько будет квадратов.

Именование процедур и переменных

Как действуют правила относительно ключевых слов, также действуют правила относительно именования процедур и переменных. Пока не производился разбор процедуры Start, но уже полезно знать, что процедуры именуются с большой буквы. Так, например, инструкция Log.String('Привет, мир!') является вызовом процедуры "String" из модуля "Log". И это точно не ключевое слово, так как заглавные буквы не все, а только первая.

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

Размещение инструкций

Часто можно встретить код, представленный ниже

Hello.odc (v3.1):

MODULE TestHello;
(* это первая программа на языке
Компонентный Паскаль. Она ничего
толком не делает, кроме вывода строки
"Привет, мир!" *)
	IMPORT Log, Math;


	PROCEDURE Start*;
		VAR
	BEGIN
		Log.String('Привет, мир!'); Log.Ln
	END Start;

BEGIN
END TestHello.

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

Размещение комментариев

Код без каких-либо комментариев является дурным тоном. Код, в котором комментариев столько, что их приходиться прокручивать чтобы увидеть код -- это тоже дурной тон. В крайнем случае, объёмные комментарии следует располагать вместе и в начале модуля. Если такой комментарий претендует на роль документации модуля -- то такой текст стоит либо вынести в модуль документации (в папке "Docu" соответствующей подсистемы файл с таким же именем, что и файл содержащий код), либо в самом файле с кодом, но после всего кода.

Правильный комментарий должен содержать пояснения неочевидных операций, например, с помощью операции "сдвиг на два бита вправо" -- на самом деле -- (* тут деление на четыре!!! *). (Как известно, операция сдвига работает часто быстрее, чем деление) Соответственно, правильный комментарий не должен пояснять очевидные вещи, например:

	PROCEDURE GetCoordX():INTEGER;
        (* эта процедура возвращает координату Х *)
	BEGIN
		RETURN x
	END Start;

Зачем вставлять этот комментарий, если из имени процедуры следует, что она возвращает координату Х?

Отступы в коде и подсветка

Практически везде по тексту модуля используются отступы. Отступы не являются требованием языка, как это сделано в python. КП прекрасно скомпилирует модуль и без отступов. Но всё-таки с отступами текст выглядит более аккуратно и ухожено. Не говоря уже о том, что такой текст легче воспринимается для понимания кода. Подсветка текста и выравнивание может быть сделана автоматически через:

Меню "Cpc" -> пункт меню "Отформатировать код"

Код будет отформатирован на столько, на сколько это вообще возможно.

Заключение

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