Этот документ описывает единый стиль кода, разработанный командой Terrasoft. Этот стиль будет полезен всем тем, кто ведет разработку или конфигурирование продуктов с использованием платформы Terrasoft.

Список терминов

Стили использования регистра букв

• Pascal – указание этого стиля оформления идентификатора обозначает, что первая буква заглавная и все последующие первые буквы слов тоже заглавные. Например, BackColor, LastModified, DateTime.
• Camel – указание этого стиля обозначает, что первая буква строчная, а остальные первые буквы слов заглавные. Например, borderColor, accessTime, templateName.

Именование идентификаторов

1. Идентификатор может содержать только английские буквы, цифры и знаки подчеркивания.
2. Идентификатор не может начинаться с цифры.
3. Необходимо избегать идентификаторов, содержащих цифры.
4. Не используйте подчеркивание для отделения слов внутри идентификаторов, за исключением отделения префикса от основной части идентификатора.
5. Старайтесь не использовать сокращения.
6. Старайтесь делать имена идентификаторов как можно короче (но не в ущерб читабельности). Главное, чтобы смысл идентификатора был понятен в используемом контексте.
7. Предпочтительно использовать имена, которые ясно и четко описывают предназначение и/или смысл сущности.
8. Старайтесь не использовать для разных сущностей имена, отличающиеся только регистром букв.
9. Если идентификатор имеет префикс, то префикс всегда пишется в нижнем регистре.
10. Старайтесь использовать имена с простым написанием. Избегайте (в разумных пределах) использования слов с двойными буквами, сложным чередованием согласных. Прежде, чем остановиться в выборе имени, убедитесь, что оно легко пишется и однозначно воспринимается на слух. Если оно с трудом читается, и вы ошибаетесь при его наборе, возможно, стоит выбрать другое.
11. Избегайте использования идентификаторов, которые совпадают с ключевыми словами используемого языка программирования.
12. Если идентификатор описывает некоторую логическую сущность, то его имя предпочтительно начинать с Is, Has или Have.

Сокращения

1. Необходимо избегать использования аббревиатур или неполных слов в идентификаторах, если только они не являются общепринятыми, или идентификатор слишком длинный. Например, пишите GetWindow, а не GetWin.
2. Не используйте аббревиатуры, если они не общеприняты в области информационных технологий.
3. Широко распространенные аббревиатуры используйте для замены длинных фраз. Например, UI вместо User Interface или Olap вместо On-line Analytical Processing.
4. Если имеется идентификатор длиной менее трех букв, являющийся сокращением, то его записывают заглавными буквами, например IO, UI. Имена длиннее двух букв записывайте в стиле Pascal, например Guid, Xml, XmlDocument.

Конфигурация

1. Основным стилем регистра букв объектов конфигурации является стиль Pascal.

Модули/Группы

1. Имя модуля/группы пишется на английском языке.
2. Имя модуля/группы может состоять из нескольких слов.
3. Разделителем слов в имени модуля/группы является символ пробела.
4. Каждое слово имени пишется с большой буквы.
5. Необходимо избегать использования цифр в имени модуля/группы, если это не обусловлено дополнительными требованиями.
6. Имя модуля пишется в единственном числе.
7. Имя группы может писаться как в единственном, так и во множественном числе, в зависимости от её предназначения.

Коды сервисов

1. Код сервиса формируется как "Префикс" + "_" + "Идентификатор", например ds_Account, sq_Offering.
2. Код сервиса должен быть идентификатором.
3. Код сервиса пишется в единственном числе.
4. Префикс кода сервиса однозначно зависит от типа сервиса и должен браться из таблицы соответствия.

^* Префикс сервиса Script может меняться в зависимости от его предназначения. Если скрипт содержит обработчики событий для сервиса Window или Dataset, то для него используется особый способ формирования кода, который описан ниже.

Заголовки и описания

1. Заголовок/описание должен раскрывать предназначение объекта.
2. Заголовок/описание должен заполняться на языке конфигурации.
3. Если заголовок/описание состоит из нескольких слов, то первое слово должно быть написано с большой буквы, а остальные с маленькой, если это не обусловлено дополнительными требованиями.
4. Заголовок сервиса должен быть уникальным в пределах конфигурации для данного типа сервиса, т.е., например, нельзя допускать существование двух сервисов типа Table с одинаковым заголовком.
5. Для некоторых объектов могут быть указаны уточнения по правилам заполнения заголовков, например, иногда заголовок должен быть равен коду объекта.

Сервисы

Script

1. Префикс сервиса Script, содержащего только библиотечные функции, формируется по стандартному правилу, т.е. берется из таблицы соответствия.
2. Префикс сервиса Script, содержащего обработчики событий некоторого сервиса, формируется как "Код сервиса" + "Script", например, если скрипт содержит обработчики событий окна wnd_Account, то его код будет wnd_AccountScript.
3. Заголовок сервиса Script должен быть равен его коду.
4. Необходимо избегать установки значения свойства Timeout=-1, т.к. это может привести к зависанию системы. Исключение могут составлять только те скрипты, логика которых действительно может потребовать длительного выполнения.
5. Все требования к оформлению программного кода на языке JScript оформлены в виде отдельной статьи.

Table

1. Заголовок сервиса Table должен быть написан в единственном числе.
2. Для таблицы должно быть заполнено описание.
3. Имена полей таблицы должны быть идентификаторами.
4. Имена полей, которые являются полями ссылки на другие таблицы и поля перечислений, должны заканчиваться на ID, например поле "Ответственный" в таблице tbl_Account должно называться OwnerID.
5. Для каждого поля таблицы должен быть заполнен заголовок.
6. Необходимо избегать создания таблиц без пяти системных полей ID, CreatedOn, CreatedByID, ModifiedOn и ModifiedByID.
7. Все системные поля должны быть объявлены в таблице первыми в следующем порядке – ID, CreatedOn, CreatedByID, ModifiedOn и ModifiedByID.
8. Для каждого поля таблицы должно быть заполнено описание.
9. Для всех полей таблицы, которые являются полями ссылки на другие таблицы, должны быть созданы индексы.
10. Имена индексов формируются как "I" + "Основная часть кода таблицы" + "Имена всех полей индекса", например, имя индекса в таблице tbl_Account по полям "Страна" и "Город" должно быть IAccountCountryIDCityID.
11. Для всех полей таблицы, которые являются полями-ссылками на другие таблицы, должны быть созданы внешние ключи.
12. Имена внешних ключей формируются как "F" + "Основная часть кода таблицы" + "Имя поля ссылки", например, имя внешнего ключа в таблице tbl_Account по полю "Страна" должно быть FAccountCountryID.
13. В случае если таблица является таблицей детали раздела/справочника, то для нее должна быть установлена та же группа таблиц (Parent Table Group), которая установлена для основной таблицы раздела/справочника. Например, для таблицы "Адрес контрагента" (tbl_AccountAddress) в качестве группы таблиц должно быть установлено то же значение, которое установлено для таблицы "Контрагент" (tbl_Account).
14. В случае если таблица является основной таблицей раздела/справочника, то для нее должно быть установлено основное отображаемое поле (Primary Display Field).
15. Для поля ID рекомендуется использовать тип "Первичный ключ" (Primary Key).
16. Для полей, которые являются ссылками на другие таблицы, рекомендуется использовать тип "Уникальный идентификатор" (Global Unique Identifier).
17. Ниже приведена таблица рекомендуемых названий полей для некоторых стандартных ситуаций.

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

SelectQuery, InsertQuery, UpdateQuery, DeleteQuery, InsertSelectQuery, ADOCommand

1. Заголовок сервиса должен быть равен его коду.
2. Для колонок, которые выбираются из основной таблицы запроса (FROM), псевдонимы (Alias) должны совпадать с именами полей таблицы.
3. Для колонок, которые выбираются из присоединенных (JOIN) таблиц, псевдоним формируется как "Имя поля ссылки" + "Имя поля из присоединенной таблицы". Например, при выборе поля "Название" (Name) из таблицы "Контакты" (tbl_Contact) в запросе на выборку контрагентов (tbl_Account) как имени ответственного (OwnerID), псевдоним колонки должен быть OwnerName.
4. Имена параметров запроса должны быть идентификаторами.
5. В случае если параметр используется для записи значения в поле таблицы, то имя параметра должно быть равно имени поля таблицы.
6. Коды фильтров должны быть идентификаторами.
7. Код основного фильтра запроса должен быть равен "Where".
8. Если запрос предназначен для основного набора данных раздела/справочника, то в нем обязательно должен быть параметр ID и фильтр сравнения с кодом ID.

DBDataset, MemoryDataset, ADODataset

1. Заголовок сервиса должен быть написан в единственном числе.
2. Имена полей должны быть идентификаторами.
3. Имена полей, которые являются полями ссылки на другие таблицы (ILookupDataField) и поля перечислений (IEnumDataField), должны заканчиваться на ID, например, поле "Ответственный" в таблице ds_Account должно называться OwnerID.
4. Для каждого поля набора данных должен быть заполнен заголовок.
5. Для набора данных типа DBDataset заголовок поля должен совпадать с заголовком поля таблицы, которому оно соответствует.
6. Необходимо избегать создания наборов данных без пяти системных полей: ID, CreatedOn, CreatedByID, ModifiedOn и ModifiedByID.
7. Все системные поля должны быть объявлены в наборе данных первыми в следующем порядке – ID, CreatedOn, CreatedByID, ModifiedOn и ModifiedByID.
8. В случае если набор данных является основным набором данных раздела/справочника, то для него должно быть установлено ключевое поле (Key Field) и основное отображаемое поле (Primary Display Field).

Window

1. Значение свойства WindowCaption окна должно совпадать с заголовком окна.
2. Высота и ширина окна должны быть кратны пяти.
3. Имена визуальных и невизуальных компонентов окна (кнопки, поля ввода, таймеры, и т.д.) формируются как "Префикс" + "Идентификатор", например, edtName.
4. Префикс имени компонента однозначно зависит от типа компонента, и должен браться из таблицы соответствия.

5. Имена визуальных компонентов окна, предназначенных для отображения и модификации одного поля набора данных (TextDataControl, LooupDataControl, и т.д.), формируются как "Префикс" + "Имя поля набора данных", например, элемент управления для поля "Название" (Name) контрагента должен называться edtName.
6. При создании нескольких кнопок на контейнере Frame/FrameGroup для соответствующего компонента необходимо устанавливать значение свойства HasSeparator=false, что позволит убрать расстояние между кнопками.
7. Если необходимо разбить элементы управления на группы внутри одного контейнера, то такое разбиение делается присвоением значения Offset (OffsetLeft, OffsetRight) равным пяти для первого элемента управления в группе.
8. Для самого нижнего контейнера Frame/FrameGroup, на котором располагаются только кнопки, должно быть установлено значение свойства GroupType=fgtFooter.
9. Если для контейнера Frame/FrameGroup значение свойства GroupType=fgtFooter, то должно быть установлено значение свойства Size=33.

ImageList

1. Заголовок сервиса должен быть равен его коду.
2. Имя изображения (Image) должно быть идентификатором.
3. Имя изображения формируется как "Идентификатор" + "Суффикс".
4. Если элемент управления имеет только один тип отображения, то суффикс изображения не используется, и в этом случае имя формируется как "Идентификатор".
5. Суффикс имени изображения однозначно зависит от типа отображения картинки элементом управления, и должен браться из таблицы соответствия.

Enum

1. Заголовок сервиса должен быть написан в единственном числе.
2. В качестве идентификаторов (ID) элемента перечисления может использоваться любая строка.
3. Код элемента перечисления формируется как "Префикс" + "_" + "Идентификатор".
4. Префикс элемента перечисления формируется из первых букв кода перечисления. Например, для перечисления enm_RelationRoleType префикс для всех элементов должен быть rrt (rrt_Contact, rrt_Account).

UserFields

1. Заголовок сервиса должен совпадать с заголовком основной таблицы (Table) раздела, для которого он создается.
2. В список сервисов и объектов, которые модифицируются сервисом UserFields, должны быть обязательно добавлены следующие объекты:
   
   1. Основная таблица раздела (Table).
   2. Основной запрос раздела (SelectQuery).
   3. Основной набор данных раздела (DBDataset).
   4. Окно основного реестра раздела (Window).
   5. Элемент управления основного реестра (DataGrid).

WorkflowAction

1. Заголовок сервиса должен быть написан в единственном числе.
2. Если элемента процесса предназначен для работы с объектами определенного раздела, то его заголовок должен совпадать с заголовком основной таблицы раздела.
3. Цвет элемента должен быть изменен на уникальный, для облегчения идентификации типа элемента на диаграмме.
4. Для каждого действия процесса должно быть создано окно редактирования, которое позволяет в удобном виде менять его параметры.
5. Имена параметров элемента процесса должны быть идентификаторами.

WorkflowDiagram

1. Диаграмма процесса должна содержать только один элемент начала процесса (IWorkflowDiagramStartItem).
2. Диаграмма процесса должна содержать как минимум один элемент завершения процесса (WorkflowDiagramFinishItem).
3. Имена параметров процесса должны быть идентификаторами.
4. Если элемент процесса (WorkflowDiagramItem) используется в скрипте процесса, то его имя должно удовлетворять всем принципам именования идентификаторов.
5. Если связь элементов процесса (WorkflowDiagramLink) используется в скрипте процесса, то ее имя должно удовлетворять всем принципам именования идентификаторов.