Доклад: Комментарии в Cache

Евгений Каратаев

Комментарии в Cache есть. Это специальным образом отмеченная программистом последовательность символов, которая не используется компилятором. В них можно писать разные полезные слова, которые останутся и которые потом можно будет прочитать, например ругательства. В комментариях можно писать на любом языке. Это общеизвестные факты. Теперь посмотрим какие именно комментарии поддерживает Cache и какие у них есть особенности.

Стандартный однострочный комментарий.

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

Текст комментария в объектный код не попадает.

При трансляции MAC Cache вставляет в первую строку INT кода отметку о дате трансляции.

Если перед комментарием есть команда, то в байт-код от комментария ничего не попадает, если нет команды или метки, то попадает внутренняя команда байт-кода «пустая операция»

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

Если комментарий начинается с первого символа строки в макрокоде, то в int коде перед ним будет добавлена втяжка. Так поступает, например, Cache3.

Стандартный двойной комментарий

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

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

Макрокомментарий

Макрокомментарий начинается с символов #; и продолжается до конца строки. Он может начинаться только с начала строки, перед ним не должно быть ни команд и меток, он занимает всю строку. Макрокомментарий удаляется препроцессором, и в int код вообще не попадает. Это очень хорошая замена стандартному комментарию, если его нужно расположить целиком на одной строке. Этим макрокомментарий удобен. В силу отсутствия в стандарте MUMPS препроцессора этот комментарий не входит в стандарт.

К особенности макрокомментариев относится то, что транслятор int кода их не видит, поскольку они удаляются препроцессором. Это приводит к тому, что при получении сообщения об ошибке в коде номер строки в int коде может отличаться от номера строки в mac коде. Этим макрокомментарий неудобен.

Включение комментариев из инклудов

Находящиеся во включаемых файлах (inc) комментарии по умолчанию в генерируемый код int рутины не включаются. Но этого можно добиться используя макродирективы #show / #noshow - первая приводит к включению комментариев из inc в int, вторая - к выключению.

Трудно представить в каких случаях это может понадобиться за исключением отслеживания порядка включения inc - при выполнении директив #define препроцессор Cache в отличие от стандартных препроцессоров не проверяет был ли этот символ определен ранее.

Однострочный косой двойной комментарий

Начинается с двух символов // и продолжается до конца строки. Ведет себя и выглядит так же как такой же комментарий в C++ или JavaScript. Поддерживается начиная с какой-то версии Cache4. Поведение полностью совпадает со стандартным комментарием, но код выглядит посовременнее. В стандарт MUMPS не входит.

Однострочный косой тройной комментарий

Начинается с трех символов /// и продолжается до конца строки. Ведет себя также как однострочный двойной косой за исключением использования в редакторе классов Cache5. Если его использовать перед методом или другим каким-либо элементом класса, то он считается вводом дескрипции к этому элементу и используется и сохраняется впоследствии в определении класса. Если нужно чтобы в дескрипцию входило несколько строк, нужно каждую из них начать с такого комментария. В стандарт MUMPS не входит.

Многострочный комментарий

Начинается с символов /* и заканчивается символами */. Выглядит как обычный сишный комментарий. Текст внутри комментария полностью игнорируется транслятором. Весьма удобен если нужно разом закомментировать большой кусок кода но оставить его в тексте рутины или для того чтобы оформить многострочное пояснение. В стандарт MUMPS не входит.

К его неудобствам относится то, что он хотя и игнорируется транслятором int кода, но не игнорируется препроцессором - наличествующие в нем директивы продолжают отрабатываться препроцессором. Поэтому можно получить определение символа или код обрамленный макроусловиями вида #if / #endif несмотря на то что эти директивы могут находиться внутри многострочного комментария.