Инструменты пользователя

Инструменты сайта


blackbox:manual:markup

1.5 Оформление модуля

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

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

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

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

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

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

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

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

  1. Не ставят после ключевых слов: IMPORT, TYPE, VAR, BEGIN — после этих ключевых слов может ничего не идти, но как правило, идёт. Если поставить сразу точку с запятой, то будет считаться, что секция программы либо ничего не содержит, либо содержит пустую инструкцию.
  2. Не ставят точку с запятой перед ключевым словом END. А зачем? Если есть ключевое слово END — и так понятно, что дальше ничего нет (хотя конечно же, никто не запрещает, и это допустимо; лучше поставить, чем не поставить)
  3. После последнего END ставится точка, а не точка с запятой. Это особый случай, когда идёт указание КП, что текст модуля закончен. Именно поэтому программисту разрешается после текста вставить КОММАНДЕР (котиков, анекдот и вообще всё что душе угодно), и КП не посчитает это за ошибку (на рисунке ниже успешно скомпилированный модуль). Эта особенность позволяет хранить вместе с кодом и описание модуля, какие-то заметки, рекомендации и т. д., при этом не перегружая и не размазывая код между обильными комментариями.
MODULE КнигаПривет;
	(* это первая программа на языке
	Компонентный Паскаль. Она ничего
	толком не делает, кроме вывода строки
	"Привет, мир!" *)
 
	IMPORT Log, Math;
 
	PROCEDURE Старт*;
		VAR
	BEGIN
		Log.String('Привет, мир!');
		Log.Ln
	END Старт;
 
BEGIN
END КнигаПривет.
 
Ха-ха! А здесь у меня будет анекдот **жирными буквами**с бородой. И это не является ошибкой! Он очень смешной))
#@!$%^4567567///./

Рис. 1 Добавление любой информации после END.

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

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

Рис. 2 Подсветка места ошибки.

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

Рис. 3 Причина ошибки в КП.

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

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

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

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

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

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

Hello.odc (v3.1):

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

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

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

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

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

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

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

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

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

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

(Подсистема Cpc может быть скачана и установлена с сайта Цинна. О такой возможности будет рассказано отдельно)

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

Если читатель обратил внимание, практически не используются расцвеченные маркеры кода. В КП код не имеет таких форм записи, которые могли бы свернуть мозг программисту. И поэтому цветовая подсветка, на самом деле — не нужна.

Сделаны лишь два исключения:

  1. Комментарии выделяются курсивом
  2. Экспортируемые процедуры и переменные подсвечиваются жирным.

9. Заключение

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

1)
можно не использовать символ подчёркивания, если все константы выносить в отдельный модуль. Тогда обращаться к таким константам можно будет примерно так:
s := мКонст.макс_длин_массива
2)
первая маленькая буква в переменной не обязывает все буквы в переменой быть маленькими. В дальнейших примерах это будет показано
3)
В стандартной сборке БлэкБокса этого компонента нет!!
blackbox/manual/markup.txt · Последние изменения: 2018/11/29 22:13 (внешнее изменение)