Правила документирования кода на RSL

Материал из RSB-Doc
Перейти к: навигация, поиск

Содержание

Документирование модулей

Описанием модуля (файла) считаются комментарии, начинающиеся с набора ключевых слов со следущим за словом двоеточием.

Ключевое слово Значение комментария
File Имя файла с расширением
Copyright RS Softlab Research. Год создания файла (никаких дефисов, подробнее о формате)
Description Краткое описание модуля
Programmed by Автор модуля (плюс номер запроса, по которому был создан файл)
Creation Date Дата создания модуля
Last Update Дата последней модификации (плюс фамилия автора изменений, плюс номер запроса)
Full Description Подробное описание модуля
Category Категория макроса. В настоящее время не используется. Список категорий будет составлен позднее.

Регистр ключевых слов не имеет значения. В одном комментарии должно быть только одно ключевое слово в начале комментария. Комментарии с описанием модуля должны располагаться в самом начале модуля перед другими комментариями, определениями и инструкциями. Они могут следовать в любом порядке, но между ними не должно быть других комментариев, без ключевых слов. Допустимы пробельные символы перед ключевыми словами и между ними и двоеточием.

Пример корректного описания модуля:

/* File:               COrptPrintForm.mac                                     */
/* Copyright:          RS Softlab Research. 2011                              */
/* Description:        Классы печатных форм отчётов                           */
/* Programmed by:      Харионовский Василий                                   */
/* Creation Date:      13.09.2011 (#26695)                                    */
/* Last Update:        01.01.2015 (Харионовский Василий) (#12345)             */
/******************************************************************************/

Или:

/* FILE         :  COrptInitForm2221.mac                                      */
/* COPYRIGHT    :  RS Softlab Research. 2012                                  */
/* DESCRIPTION  :  ФИ отчета 2.2.2.1 "Состояние склада"                       */
/* PROGRAMMED BY:  Петров Игорь                                               */
/* CREATION DATE:  12.09.2012                                                 */
/* LAST UPDATE  :  30.01.2015, #12345, Петров Игорь                           */
/******************************************************************************/

Или:

// FILE:              COdlgDocumentLinkMap.mac
// COPYRIGHT:         RS Softlab Research. 2014
// DESCRIPTION:       Карта связей документов
// PROGRAMMED BY:     Роман Сапрун
// CREATION DATE:     31.12.2014

Некорректное описание модуля:

/************************************************************************************
 FILE         :     COAppClasses.mac
 
 COPYRIGHT    :     R-Style Software Lab. 2005-2015
 
 DESCRIPTION  :     Прикладные классы
 
 PROGRAMMED BY:     Головкин Константин
 
 CREATION DATE:     29.03.2005
************************************************************************************/

Некорректность вышеприведенного описания в следующем:

  1. все ключевые слова в одном комментарии;
  2. между началом комментария и первым ключевым словом есть непробельные символы (не должно быть строки /***********);
  3. старое наименование организации.

Обращаю внимание, при правке файла с некорректным описанием необходимо заменить описание на корректное. Но если описание соответствует требованиям, то изменять его под свой стиль оформления не разрешается.

Документирование классов

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

Пример:

]
class TExample
/*Описание класса*/
/*Уже не относится к описанию класса*/
  ...
end;
 
class TExample2
  var temp:variant;
/*Не является описанием класса*/
   ...
end;
 
class TExample3 // Описание класса в одну строку
  ...
end;

Документирование функций

Функции документируются аналогично классам.

Пример:

]
macro ExampleMacro()
/*Описание функции*/
  ...
end;

Документирование переменных и параметров функций

Описанием переменной или параметра функции считается комментарий, следующий непосредственно после объявления переменной или параметра, после инициализации (если есть), но перед разделителем ("," или ";").

Примеры документирования переменных

]
var tmp:integer /*Описание переменной tmp*/;
var tmp1/*Описание переменной tmp1*/,tmp2:string = "Строка"/*Описание переменной tmp2*/;

Примеры документирования параметров функций

]
macro Func( prm1:bool   /*описание параметра prm1*/,
            prm2        /*описание параметра prm2*/,
            prm3:string // описание параметра prm3
          )
  ...
end;

Правила именования в RSL

Основные правила именования

Для именования переменных используется модифицированная венгерская конвенция:

  1. Имена переменных-членов класса начинаются с ‘m_’, статические — ‘s_’.
  2. Глобальные переменные — ‘g_’ или, если они являются основополагающими, ‘the’
  3. Если переменная является ссылкой, ее имя начинается с ‘ref'
  4. По типам:
    • Целое — ‘i’
    • Строка — ‘s’, ‘str’
    • Булевский тип — ‘is’, 'b'
    • Вещественные числа — ‘f’, ‘lf’
    • Числа с фиксированной точкой: decimal — ‘n’, money — 'm'
    • Дата, дата и время — 'dt'
    • Время — 't'
    • Переменная типа variant — ‘v’
    • Ссылка на функцию, функцию-член класса — 'ref'
    • Массив — 'arr', 'tarr'
    • Ссылка на объект RSL — 'o', 'obj'
    • Ссылка на объект ActiveX — 'ax'
    • Ссылка на объект источника данных (RSObject) — 'ds'

Имена классов начинаются с прописной буквы:

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

Имена функций должны отражать их функциональность. Расширение файлов — «.mac». В имени файла можно использовать более 8 букв, но нельзя использовать пробелы.

Именование объектов визуального представления (формы, поля, кнопки)

Для именования ссылок на объекты визуального представления используются следующие префиксы:

Соглашение об именовании классов справочников, диалогов редактирования объектов и файлов макросов

Все имена классов справочников (форм списка и диалогов редактирования) должны состоять из четырех частей:

  1. лидирующий символ «Т»;
  2. префикс подсистемы в верхнем регистре (см. Таблица кодовых букв подсистем, как правило, RD)
  3. префикс вида формы:
    • форма списка — «frm»,
    • диалог редактирования — «dlg»;
  4. смысловое имя справочника (по-английски).

Например, если создается справочник «Единица измерения», правильными именами классов формы списка и диалога редактирования будут соответственно: TRDfrmMeasureUnit и TRDdlgMeasureUnit. При разработке альтернативных форм справочников необходимо расширять смысловое имя справоч-ника, например TRDdlgMeasureUnitLite или TRDdlgMeasureUnit1. Имена файлов макросов образуются из имен соответствующих классов путем отбрасывания первой буквы «Т» и добавления расширения «.mac». Для предыдущего примера файл с описанием клас-са TRDfrmMeasureUnit должен называться RDfrmMeasureUnit.mac.

Допустима также транслитерация русских названий

Таблица кодовых букв подсистем

Подсистема Кодовые буквы
Бухгалтерский учет AC
Общие прикладные объекты CO
Торговый зал PS
Общесистемные справочники RD
Системные объекты SS
Склад WH

Самое последнее актуальное состояние можно посмотреть в таблице sModule базы

Таблица кодовых букв интерфейсов

Значение Кодовые буквы
Основная Форма объекта frm
Модальный Диалог Dlg
Обработчик меню Cmd
Действие агента AgentAction
Отдельное приложение App
Базовые наборы классов Base
Дополнительные списки Detail
Верхняя область АФ документа DocHead
Фильтр для реестра документов filterRegister
Макро функция Macro
Условия запуска Этапа СДО SchemCondition
Форма Инициализация КО tskInitForm
Форма Выполнения КО tskMain
макрос комплексной, не подразуме-вающий форму инициализации, либо включающий в себя сразу весь функционал tskStepForm

Правила кодирования на RSL и использования RS-Forms

RSL

  1. В начале каждого макроса нужно добавлять строку cpwin.
  2. Все директивы IMPORT должны быть вверху файла, через пустую строку от cpwin
  3. Каждый импортируемый модуль должен быть выделен в отдельную строку и иметь свою дирек-тиву Import
  4. Не должно быть закомментированных классов и функций
  5. Комментарии автогенератора кода должны быть удалены
  6. Не должно быть объявлено функций, которые не используются
  7. Макро функция не должна принимать более 5 параметров. В случае такой необходимости нужно соз-давать отдельный класс с наименованием ClassParamИмяФункции
  8. В Макро файле не должно быть строк с количеством символов более 150
  9. функции класса, которые нельзя переопределять в наследниках, должны иметь префикс "SEAL_"
  10. Максимальная вложенность while, for, if не более 5, рекомендуется не больше 2
  11. var, and, not, or, private, local, debugbreak, file, weakref, cpwin, elif, else, for, if, while, break, continue, return-- Должны быть в нижнем регистре
  12. Разделение классов и макро функций должно быть не более 2-х пустых строк. Макро файлы реко-мендуется объединять в себе классы и функции относящиеся к одной функциональности Например: RDfrmInfoAA.mac. Содержит основной класс формы и классы кнопок вызова основной формы и класс закладки на форму

Все пункты, описанные выше, обязательны к исполнению, если разработчик не может обосновать обратного.

Использование описаний типов

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

Пример:

macroSampleFunc(_iParm1:integer, _vParm2:variant):string
varsRetVal:string;
  ...
returnsRetVal;
end;

вместо

macroSampleFunc(_iParm1, _vParm2)
varsRetVal;
  ...
returnsRetVal;
end;

Вложенные классы и функции

При разработке классов и функций нельзя использовать вложенные классы и функции:

class T1
  ...
class T2
    ...
end;
  ...
end;
macro M1
  ...
macro M2
    ...
end;
  ...
end;
macro M
  ...
class T
...
end;
  ...
end;

Язык разрешает такие конструкции, однако работают они некорректно! Иногда RS-клиент молча падает. Можно объявлять только функции внутри классов.

RS-Forms

Правила именований визуальных библиотек (lbr)

  1. LBR должна именоваться по шаблону COfrmAttestDoc_AA.lbr где :
    1. CO - первый два символа означают подсистему к которой относится функциональность
    2. frm - Означает интерфейсную сущность Таблица кодовых букв интерфейсов Может быть не указанно если файл содержит несколько сущностей
    3. AttestDoc - Смысловое описание сути файла
    4. _AA - Принадлежность к проекту (Должно быть во всех файлах создаваемых в Авто Альянсе)

Закладки на TabControl

При разработке ресурсов необходимо обращать внимание на расположение закладок в TabControl. За-кладки должны быть сверху. На то есть две причины:

  1. Единообразие системы;
  2. Некорректная отрисовка закладок RS-Forms, если они расположены сбоку или снизу, при использовании некоторых стилей XP

При обнаружении в существующих ресурсах закладок, расположенных снизу или сбоку, необходимо исправить ресурс.

Стандарты наименования объектов

Стандарты наименования объектов и стандарты визуальной части.

(Не касается объектов, таблиц, полей и т.д. старых систем, которые могут использоваться в проекте)

Правила наименования объектов

Наименование таблиц и полей таблиц

1. Наименование таблиц в БД должно начинаться с двух маленьких символов указывающих под-систему, к которой относится данная таблица (см. Таблица кодовых букв подсистем.)

2. Для таблиц справочников после букв подсистемы указывается тип справочника:

3. Далее должно следовать имя объекта, к которому относится таблица на английском языке, если таблица описывает подобъект далее должно следовать имя подобъекта и т.д. Допускаются со-кращения имен объектов и подобъектов (например, таблица coContractState может быть названа coContrState).

4. При наименовании полей, желательно отражать в названии логический смысл данного поля, желательно также придерживаться стандартных имен для стандартных полей, таких как «ID» для уникального идентификатора, «ParentID» для ссылки на родителя в дереве, «Code» для символьного кода, «Name», для имени, «Numb» для номера и т.д. Для ссылок рекомендуется формировать имя по имени объекта или подобъекта, на который она ссылается и добавки «ID» (например ContractID или RouteStageID). Нельзя использовать для названия полей имена, за-резервированные SQL-сервером. Список зарезервированных слов можно посмотреть в MSDN (ms-help://MS.VSCC.v80/MS.MSDN.v80/MS.SQL.v2005.en/tsqlref9/html/ed8b3e27-6796-40f0-aef3-0cac5e0e2418.htm)

5. При наименовании полей-флагов желательно начинать наименование поля с приставки «Is» и далее отражать логическое имя (например, IsExecuted – признак исполнения, IsSigned – при-знак подписания и т.д.).

Наименование объектов, подобъектов, полей и методов в TypeInfo

  1. Название таблицы должно соответствовать названию объекта (перевод или транслит)
  2. Ссылка на объект имеет то же имя, что и сам объект, на который она ссылается. Например, ссылка на валюту в объекте «Договор» называется «Валюта».
  3. Имя поля должно отражать логическую сущность этого поля, желательно придерживаться стан-дартных имен полей, таких как «Идентификатор» для уникального идентификатора, «Роди-тель» для ссылки на родителя в дереве, «Код» для символьного кода, «Наименование», для имени, «Номер» для порядкового номера и пр.
  4. В логических полях желательно по возможности избегать слова «признак», и использовать краткую форму прилагательного. Например, «Проведен», «Изменен» и т.п.
  5. В именах нельзя использовать символы косой черты “\”, кавычки и апострофа.(а также мно-гих других, которые преобразуются RSL либо считаются служебными в SQL)

Наименования объектов клиентской части приложения

см. Правила именования в RSL

Список зарезервированных слов меню - функциональных клавиш

Англ Рус Значение и поведение Есть на кнопке Есть в меню Функциональные клавиши
OK Да Подтверждение выпол-нения запрошенного или инициированного действия + - <Return>, <Enter>
Cancel Отменить Отказ от запрошенного или инициированного действия + - <Esc>
New Новый Создание нового доку-мента, “папки” и пр. + + Ctrl-Н (Ctrl-Y)
Open Открыть Открытие некоторого документа, “папки” и пр. + + Ctrl-O (Ctrl-J)
Close Закрыть Закрыть то, что открыто по “Открыть” + + Ctrl-З (Ctrl-P)
Exit Выход Завершение работы приложения (программы в целом) - + Alt-F4
Help Справка Открыть окно справки + (Контекстно) + F1
Save Сохранить Записать в БД то, что введено или изменено + (То, что введено в ок-не) + (То, что изменено в Документе) Ctrl-S
SaveAs... Сохранить как... - + -
Undo Восстановить Отменить изменения в некотором фрагменте (окне, ...) - + Ctrl-Z
Cut Вырезать Вырезать в буфер некоторый фрагмент информации - + Ctrl-X
Copy Копировать Копировать в буфер некоторый фрагмент информации - + Ctrl-C
Paste Вставить Вставить из буфера некоторый фрагмент информации - + Ctrl-V
Print Печатать Начать процесс печати текущего документа - + Ctrl- P

Стандартные акселераторы

Кнопка Описание действий
SHIFT+F1 Включить режим контекстно-зависимой помощи (режим, в котором указание мышью на объект вызовет контекстную помощь для объекта) (What’sThis?).
SHIFT+F10 Показать контекстное pop-up меню.
SPACEBAR Выбрать (то же, что click кнопкой 1 мыши)

Если контекст (напр., текстовое окно) использует SPACEBAR для ввода пробелов, можно использовать CTRL+SPACEBAR.

ALT Активизировать меню
ALT+TAB Показать следующее первичное окно (или приложение).

Использование SHIFT с этой комбинацией клавиш изменяет направление на обратное

ALT+ESC Показать следующее окно
ALT+SPACEBAR Показать pop-up menu для окна
ALT+HYPHEN Показать pop-upmenu для активного дочернего окна (MDI).
ALT+ENTER Показать таблицу свойств для текущего элемента (выделения)
ALT+F4 Закрыть активное окно.
ALT+F6 Переключиться в следующее окно приложения (между немодальными вторичными окнами и их первичным окном)
ALT+PRINT SCREEN Образ активного окна в Clipboard.
PRINT SCREEN Экран в Clipboard.
CTRL+ESC Встать на кнопку Start.
CTRL+F6 Показать следующее дочернее окно (MDI)
CTRL+TAB Показать следующую страницу или дочернее окно (MDI)
ENTER (ALT+ENTER) В контексте списка записей (объектов) - открыть форму работы с записью (объектом)
INS (Insert) В контексте списка записей (объектов) - добавить запись (объект)
DEL (Delete) В контексте списка записей (объектов) - удалить запись (объект)
F5 В контексте списка записей (объектов) – перечитать список (освежить)

Требования к документированию кода

При документировании кода как минимум необходимо описывать следующие объекты:

  1. Модули
  2. Глобальные константы
  3. Глобальные переменные
  4. Классы
  5. Глобальные функции
  6. Функции классов
  7. Параметры всех функций (в т.ч. конструкторов классов)
  8. Внешние переменные классов

Дополнительно

  1. Во всех случаях, кроме описания переменных и параметров, допустимы многострочные описания. Разумеется, они должны быть оформлены многострочным комментарием (/*…*/). В принципе, технически многострочные описания допустимы и для переменных/параметров, но они сделают код намного менее читабельным, поэтому настоятельно не рекомендуются;
  2. В описаниях элементов можно использовать следующие теги wiki-разметки:
    • Ссылка [[текст ссылки]];
    • Выделенный '''Полужирное начертание''';
    • Курсив ''Курсивное начертание'';
    • Формула <math>Вставьте сюда формулу (LaTeX)</math>;
    • Маркированный список *;
    • Нумерованный список #;
Личные инструменты
Пространства имён
Варианты
Действия
Навигация
Для разработки
Инструменты