Стандарт разработки COINS Ltd

Разработка этого стандарта была начата в 2001 году, одновременно с принятием решения о конверсии традиционного терминального приложения в распределенную архитектуру с использованием web-интерфейса как основного пользовательского интерфейса. При разработке стандарта использовался рассмотренный ранее стандарт от Fast 4GL Systems, так, раздел «Дизайн базы данных. Общие положения» включен практически дословно. Стандарт активно развивался и в настоящее время состоит из ряда документов, основными являются следующие три:

• Programming and Design Guide – руководство по проектированию и программированию
• Code Naming conventions – соглашение о наименованиях для кода
• Web Naming Conventions – соглашение о наименованиях для интерфейса

Programming and Design Guide

Первый документ включает раздел «Database Design», а также целый ряд разделов, описывающих технологическую среду (framework), используемую при разработке приложения. Раздел «Naming Conventions», содержащийся в первоначальной версии документа, был позднее из него вынесен и разделен на два – для кода и для пользовательского интерфейса.

Ниже изложены  некоторые положения данного документа:

• Имена таблиц должны иметь вид XX_Name
  где
  XX                – двухсимвольный код модуля
  Name           – краткое описательное название сущности
• Описание таблицы должно содержать разделенный вертикальной чертой (pipe) список атрибутов таблицы, например:
  “DUMPCODE=S|TABLE_ID=cio|REPLICATE=DW”
  где
  DUMPCODE               S – статические данные
  C – конфигурационные данные
  T – транзакционные данные
  TABLE_ID                    Уникальный трехсимвольный идентификатор таблицы
  REPLICATE                  Указатель необходимости репликации (D – удаление, W – запись)
• Триггеры должны быть обязательно определены для событий WRITE, DELETE, REPLICATION-CREATE, REPLICATION-WRITE и REPLICATION-DELETE.Имена триггеров должны иметь вид XXX-[r]{c|w|d}t.p
  где
  XXX               Идентификатор таблицы
  r                      Индикатор репликационного триггера
  c, w, d            Create, Write и Delete триггер соответственно
• Все таблицы должны иметь метку (Label), описывающую сущность в единственном числе (Office, а не Offices).
• Имена полей должны иметь форму XXX_Name
  где
  XXX             Уникальный идентификатор таблицы
  Name           Краткое описательное название поля
• Имена индексов должны иметь вид XXX_key[n]
  где
  XXX               Уникальный идентификатор таблицы
  N                    Необязательный последовательный номер

Code Naming conventions

Соглашение о наименованиях, как следует из названия, определяет принципы именования объектов кода. Некоторые основные положения данного документа приведены ниже.

Переменные и параметры

Используется венгерская нотация для имен переменных и параметров со следующей структурой:

[ s ] { t [n] VariableName}

Где:

	s	Scope/Parameter Indicator:
 	пусто	уровень программы (Program scope)		
	q	Параметр программы 
	l	Уровень внутренней процедуры, функции, триггера (Local)
	p	Параметры внутренних процедур или функций
        t	Тип данных:
	c	Character, Long Character
	I	Integer (INT, INT64)
	j	Date (от Julian)
	b	Logical (Boolean)
	d[n]	Decimal, где n – точность хранения, 2 знака после запятой, если не указано
	o	Com-handle (от Object)
	h	Handle
	r	ROWID
	w	RAW
	k	RECID, тип не должен использоваться в новом коде
	m	MEMPTR
	bl	BLOB
	cl	CLOB
	jt	DATETIME
	jtz	DATETIME-TZ

Для параметров может быть дополнительно указан индикатор типа Out или InOut.

VariableName	смысловое имя переменной или параметра, заглавная буква в начале каждой части 
 		имени.
 		Исключения: i, j и k – только для целых переменных в локальном контексте.
 		В качестве рабочих символьных переменных в локальном контексте можно
 		использовать переменные c и lcStr.

Variable names

• Имя переменной должно полно и точно описывать сущность, которую эта переменная представляет.
• Имена должны быть конкретными. Следует избегать имен типа x, temp, и i.
• Избегайте сокращений, кроме случаев когда они являются общепринятыми и широко используемыми.
• Имена логических переменных должны подразумевать значения True или False. Имя должно описывать положительное значение, например bVisible, lbRowAvailable.

Методы

Функции

Для имен функций используйте описание возвращаемого значения. Например: nextCustomerID(), printerIsReady(),currentFontColor()

Внутренние процедуры

Для имен внутренних процедур используйте сильный глагол с последующим объектом. Процедуры с функциональной связностью обычно выполняют некоторую операцию над объектом. Например:  printDocument(), calcMonthlyRevenues(), checkOrderlnfo().

Методы классов

Для имен методов класса не следует включать имя объекта, так как имя объекта включается в вызов. Например: document:print(),  orderInfo:check(), monthlyRevenues:calc(). Имена вида document:printDocument() являются избыточными и могут стать неточными для производных классов.

Временные таблицы

Имена временных таблиц имеют следующую структуру:

tt{Name}

где

tt            фиксированный текст

Name   Имя сущности

Если временная таблица определяется подобно таблице базы данных, следует использовать имя таблицы базы данных после префикса tt. После имени таблицы может быть добавлено описание.

Примеры:

ttReport

ttJc_job

ttJc_jobNew

Поля

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

Буферы

Имена буферов имеют следующую структуру:

[s]{table_name}[BufferName]

Где

s              Индикатор области видимости:

пусто    уровень программы, глобальный буфер

q             параметр программы

l               локальный буфер

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

table_name – оригинальное имя таблицы, строчными буквами

BufferName – дополнительный текст, описывающий буфер.

Web Naming Conventions

Этот документ является наиболее специфическим для принятой архитектуры приложения и определяет стандарт именования объектов web-интерфейса и серверных объектов.

 Серверные объекты

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

Имена серверных объектов для конкретных таблиц имеют следующую структуру:

xxcttt[n[n[n]]].{p|i}

где

xx                           Код модуля

c                              Класс

• • • • a – ajax XML service
      • f – форма
      • g – программа генерации записей
      • r – программа генерации отчета
      • s – super процедура
      • u – утилита
      • v – валидация

ttt                           Идентификатор основной таблицы

[n[n[n]]]              Последовательный номер (опция)

Include-файлы, использующиеся исключительно данным объектом, должны именоваться так же, как использующий их объект. Если они используются несколькими объектами, следует именовать их независимо, но используя это же правило.

Если основная таблица не может быть идентифицирована, идентификатор ttt может быть опущен.

Исключения

Допускаются исключения для следующих случаев:

Триггеры базы данных:

ttt-{wt|dt|rct|rdt|rwt}.p

Процедуры обслуживания таблиц (RSPs – Record Service Procedures):

ttt-rsp.p

Стандартные include-файлы для таблиц:

ttt-gen.i

ttt-val.i

Процедуры обслуживания форм параметров отчетов:

xxfrep.p

Web и ESB сервисы

XXesbnnn.p

XXwsnnn.p

Где

esb, ws – фиксированный текст

Функции меню

Функции меню должны именоваться по основной используемой таблице в следующей форме:

%WXXnnnmCTTT[Y|Tn|Sn]

где

%W        фиксированный текст (указывает на стандартную web-функцию)

XX          код модуля

C             класс

• • • B-Browse
    • F-Form
    • G-Grid
    • H-Tab Menu (Tab menu or Container Menu)
    • L-List
    • S-Summary
    • R-Report
    • U-Utility
    • W-Web Page

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

nnn        последовательный номер функции

m            дополнительный номер (часто 0 – ноль)

[Y]          тип подфункции

• • • A-Add
    • U-Update
    • D-Delete
    • M-Detail (More)
    • X-Export
    • G-Generate
    • B-Bulk
    • O-Options Menu
    • L-Link/Actions Menu

Tn           T-Tab , n-последовательный номер

Sn           S-Security function, n-последовательный номер

Примеры:

%WPL2000BAVM                            Supplier Browse (Maintenance/Lookup)

%WPL2000SAVM                            Supplier Summary/Update

%WJC2000BJOB                               Contract Browse

%WJC2001BJOB                               Contract Browse/Lookup (Alternative)

%WPL1010BCOB                              P/L Invoice Batch Browse

%WPL1010BAIN                               P/L Invoice Batch Invoice Browse

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

Первые три цифры номера функции обычно идентифицируют бизнес-процесс (унаследовано от оригинального терминального приложения):

100-199                Input

200-299               Maintenance/Lookups

300-399                Reports

500-599                Enquiries

700-799                Processing

900-999                Administration

Заключение

Помимо упомянутых выше трех документов, внутренняя документация разработчика включает целый ряд руководств по решению типовых задач программирования, а также справочную Wiki-систему.

Другими словами, степень регламентированности деятельности программиста – чрезвычайно высокая.  В то же время, качество кода и степень его соответствия принятым стандартам, все еще оставляют желать лучшего. При весьма значительных трудозатратах на ревью готового кода при завершении задачи.

С целью уменьшения трудозатрат и улучшения качества кода была предпринята попытка внедрения автоматического анализа кода на соответствие стандартам и практикам с помощью ProLint.