4.1. Как сделать код “комильфо”?

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

• Наличие подробных и внятных комментариев. Каждое неочевидное действие должно сопровождаться пояснениями.
  
• Внятность имен. Все имена должны быть понятными, иметь схожую структуру и использовать однотипную мнемонику.
  
• Единообразие оформления. Одни и те же конструкции должны оформляться одним и тем же способом.
  
• Обозримость кода. Выражение всякой “мысли” не должно занимать более одного экрана.
  
• Универсальность технических приемов. Одни и те же задачи всегда решаются одним и тем же способом, если нет особых причин применить другой способ.
  

4.2. Комментируйте код

Старайтесь комментировать все действия, имеющие самостоятельный смысл. Обязательно помещайте комментарии в заголовках макросов. Участки кода, имеющие существенно разный смысл, можно отделять друг от друга пустыми строками — Парсер их оптимизирует при обработке. Комментируя схожие по характеру действия, старайтесь использовать схожую лексику и схожие грамматические конструкции.

Напоминаем предусмотренные в Парсере способы комментирования кода.

• Оператор rem (см. п. 3.15.1).
  
• Любая строка, имеющая в первой колонке символ #, является комментарием.
  
• Комментарий можно поместить после закрывающей квадратной скобки в заголовке макроса с явным указанием параметров (см. п. 1.3.3).
  

4.3. Внимательно относитесь к именам

Имена должны быть информативными. Они обязаны соответствовать назначению тех сущностей, которым присвоены. Не стоит давать макросу имя любимой кошки (девушки, рок-звезды и т. д.), вспомните лучше, какую задачу он решает. Избегайте абстрактных и многозначных существительных. Имена вроде parameter, x2378 или string ни о чем не говорят. Стремитесь к внятности имен. Хороший способ формирования осмысленных имен — придерживаться принципа “глагол_существительное”, так, макрос, сохраняющий настройки, можно назвать save_options.

Не используйте аллитераций и непонятных аббревиатур. Старайтесь, чтобы имена были легко произносимы и однозначно воспринимались на слух. Каково будет объяснять коллеге по телефону, что в код необходимо добавить вызов макроса _RaCS_zajyka_moya? Старайтесь сделать код понятным, а не забавным. Возможно, конструкции ^if[$en;loran] или ^config[vam] выглядят смешно, но все-таки код — не место для каламбуров.

Имена i, j, k позволительно давать только счетчикам циклов.

Парсер различает регистр букв в именах, однако категорически не рекомендуется использовать имена, отличающиеся только регистром. Не следует использовать похожие имена, а также имена, одно из которых является началом другого (например, extrapolation и extra).

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

Помните, что имена переменных доступны во всем коде, вовлеченном в процесс обработки одного шаблона. Если вы подгружаете макросы с помощью оператора macro_use, убедитесь, что они не “испортят” нужные вам переменные.

4.4. Макросы должны быть обозримыми

Стремитесь к тому, чтобы макрос умещался на одном экране при стандартном разрешении монитора. Постарайтесь уложиться в 30 — 40 строк. Человек слаб, поэтому, разбирая текст макроса из двух тысяч строк, может впасть в грех злословья. Помните об этом и не подводите коллег.

4.5. Правильно структурируйте код

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

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

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

4.6. Не используйте оператор form вместо number

Не используйте оператор form для получения численных значений, подставляемых в другие операторы. Вместо него используйте оператор number, например:

^sql[DELETE FROM people WHERE id=^number[id]]

Иначе любой подрастающий хакер сотрет все ваши данные раньше, чем вы успеете нажать на Reset.