Cоглашения по оформлению программного кода на языке jscript

Метки записи:

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

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

Термин Определение
Оператор (Operator) Например, +, -, *, !

 
Инструкция (Statement) Например, "a = b;", "if (a) {}"
Выражение (Expression) Например, "a – b + c ", "a == 1"

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

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

Структура тела скрипта

// ----------------------------------------------------------------------------

// Код сервиса скрипта

// ----------------------------------------------------------------------------

 

Глобальные переменные

 

Вызов методов инициализирующих скрипт

 

Процедуры и функции скрипта

 

// ----------------------------------------------------------------------------

// Event handlers

// ----------------------------------------------------------------------------

 

Обработчики событий

Примеры:

// ----------------------------------------------------------------------------

// wnd_CampaignsWorkspaceScript

// ----------------------------------------------------------------------------

 

var CampaignsWorkspace = new Object();

 

function Initialize() {

      InitializeGroups('tbl_CampaignGroup', 'ds_CampaignInGroup', 'CampaignID');

      InitializeGridData();

}

...

 

// ----------------------------------------------------------------------------

// Event handlers

// ----------------------------------------------------------------------------

 

function dlGroupsOnDatasetAfterPositionChange(Dataset) {

      scr_BaseWorkspace.dlGroupsOnDatasetAfterPositionChange(Dataset);

      if (BaseWorkspace.GroupsWereInitialized){

            RefreshCampaigns();

      }

}

...

Процедуры/Функции

  1. Используйте глаголы или комбинацию глагола и существительных, глагола и прилагательных для имен процедур и функций.
  2. Имя функции, выполняющей поиск или получение некоторого значения, должно начинаться с Get.
  3. Имя функции, выполняющей некоторую проверку и возвращающее логическое значение, должно начинаться на GetIs, GetHas или GetHave.
  4. Имя функции, выполняющей установку некоторого значения должно начинаться с Set.
  5. Необходимо избегать большого количества строк в теле процедур и функций. Если количество строк достигло 100, то необходимо вынести часть логики в отдельные процедуры.
  6. В теле процедур и функций запрещены вызовы обработчиков событий.

Примеры:

function EnableAllFilters() {}

function GetParameterValue() {}

function GetIsRecordAccessAllowed() {}

function SetParameterValue() {}

Обработчики событий

  1. Имя обработчика события формируется как "Имя объекта" + "Имя события".
  2. Не рекомендуется изменять имена обработчиков событий, сгенерированных автоматически.
  3. Рекомендуется выносить код обработчиков событий в отдельные процедуры, а в коде обработчиков делать вызовы этих процедур.

Параметры

  1. Необходимо избегать указания типа в имени параметра.
  2. Не усложняйте прототип процедуры/функции "зарезервированными" параметрами, которые, возможно, будут использоваться в будущих версиях реализации.
  3. Имена параметров не должны совпадать с именами глобальных переменных.

Оформление кода

  1. Используйте табуляцию, а не пробелы, для отступов и оформления блоков. Для сдвига блока используйте один символ табуляции.
  2. При форматировании текста (кроме отступа в начале строки) используйте пробелы.
  3. Избегайте строк длиннее 80 символов, переносите инструкцию на другую строку при необходимости.
  4. При переносе части кода инструкций и описаний на другую строку вторая и последующие строки должны быть сдвинуты вправо на одну табуляцию по отношению к первой строке инструкции.
  5. При переносе части кода инструкций и описаний на другую строку оставляйте операторы на предыдущей строке. Не начинайте новую строку с оператора.
  6. Избегайте лишних скобок, обрамляющих выражения целиком. Лишние скобки усложняют восприятие кода и увеличивают возможность ошибки.
  7. Не размещайте несколько инструкций на одной строке. Каждая инструкция должна начинаться с новой строки.
  8. Необходимо избегать переноса на новую строку одного только операнда.

Примеры:

LongMethodCall(Expression1, Expression2, Expression3,

      Expression4, Expression5);

 

Var1 = a * b / (c - g + f) +

      4 * z;

 

Var2 = (a * (b *

      (c + d) +

      e * (f / z)) + 4);

Пустые строки

  1. Запрещено использование двух пустых строк подряд.
  2. Используйте одну пустую строку между процедурами и функциями.
  3. Если переменные в методе объявляются отдельным блоком, используйте одну пустую строку между их объявлением и инструкцией, идущей за этим блоком.
  4. Используйте одну пустую строку между логическими частями в процедуре.
  5. Используйте одну пустую строку для отделения глобальных переменных или процедур от комментария – заголовка скрипта.
  6. Используйте одну пустую строку для отделения процедур и обработчиков событий от комментария – заголовка обработчиков событий (Event handlers).

Пробелы

  1. После запятой должен быть пробел. После точки с запятой, если она не последняя в строке (например, в инструкции for), должен быть пробел. Перед запятой или точкой с запятой пробелы не ставятся.
  2. Все операторы должны быть отделены пробелом от операндов с обеих сторон, за исключением унарных операций.
  3. Для открывающей круглой скобки пробел ставится только слева, а для закрывающей только справа.
  4. Если открывающая фигурная скобка "{" является не первым символом в строке, то она отделяется от предыдущего символа пробелом.
  5. Запрещено использование двух пробелов подряд.

Примеры:

a=b; // Неверно

 

a = b; // Верно

 

for (var i = 0; i < 10; ++i){ // Неверно

}

 

for( var i = 0 ;i< 10;++i) // Неверно

 

for (var i = 0; i < 10; ++i) { // Верно

}

 

if(a==b){ // Неверно

}

 

if (a == b) { // Верно

}

Локальные и глобальные переменные

  1. Необходимо избегать указания типа в имени переменной.
  2. Имена локальных переменных не должны совпадать с именами глобальных переменных.
  3. Счетчики циклов традиционно называют маленькими буквами i, j, k, l, m, n.
  4. Имя основной глобальной переменной скрипта формируется отбрасыванием префикса и суффикса кода скрипта.
  5. В одной инструкции var разрешается объявлять только одну переменную.
  6. Если несколько инструкций var идут подряд, то счетчики циклов объявляются самыми последними.
  7. Инициализируйте переменные при объявлении, если это возможно.
  8. Запрещено использование одной и той же переменной для хранения значений различных типов.

Примеры:

var Var1, Var2; // Неверно

 

var Var3 = 0; // Верно

var Var4 = 0; // Верно

var i = 0; // Верно

var j; // Верно

var k; // Верно

 

var tmp1; // Неверно

 

Var3 = "Строка" // Неверно

Комментарии

  1. Комментарии пишутся на языке конфигурации (русский).
  2. Не используйте многострочные (/*...*/) комментарии. Их использование разрешается только для временного комментирования блока кода.
  3. Для описания сути некоторого участка кода, пояснений к алгоритму и другой важной информации используйте несколько подряд идущих однострочных комментариев (//...). Между группой комментариев и собственно кодом поставьте пустую строку. Это покажет, что комментарий относится к блоку кода, а не к конкретной инструкции. Напротив, если комментарий относится к конкретной инструкции, удалите все пустые строки между комментарием и инструкцией.
  4. Не рекомендуется использование комментария в одной строке с инструкциями. Такие комментарии рекомендуется располагать непосредственно над инструкцией.
  5. Отделяйте текст комментария от символов комментария одним пробелом: "// Текст комментария".
  6. Пишите каждое предложение комментария, начиная с большой буквы.
  7. Между предложениями комментария ставится пробел.
  8. Точка в конце комментария не ставится.
  9. Комментируя код, старайтесь объяснять, что он делает, а не какая операция производится. Так, инструкции if соответствует выражение «если... то...», причем часть, идущая за «то», является кодом, который будет выполняться, если выражение в if будет верным. Таким образом, для конструкции "if (File.Exists(somePath))", нужно написать комментарий "// Если выбранный файл существует, то...", а не "// Производим проверку на наличие файла и, если он имеется, удаляем его". Часть предложения, идущую за «то», вписывайте непосредственно перед выполнением конкретных действий. Для инструкций, осуществляющих действия, пишите "// Производим..." или "// Делаем...", где вместо троеточия вписывайте описания действий. Описывая действия, старайтесь описывать суть происходящего, а не то, что делают те или иные операторы. Так, совершенно бессмысленны комментарии вроде: "Присваиваем переменной a значение b" или "вызываем метод f".
  10. Если блок кода комментируется с целью дальнейшей модификации или удаления данного блока, то непосредственно перед ним должен идти блок комментария "// TODO - ...", в котором вместо троеточия необходимо указать, какие именно действия должны быть произведены с данным блоком.
  11. Если функция имеет пустое тело или блок не содержит инструкций, то в нем должен быть добавлен комментарий "// Ничего не делаем"

Примеры:

// Комментарий к конкретной инструкции

a = b + c;

 

// Комментарий к блоку инструкций. Комментарий состоит из нескольких предложений

 

a = b + c;

a++;

 

// TODO – Удалить после проверки

/*

function Func1() {

...

}

 

function Func2() {

...

}

*/

Инструкции

  1. Каждая инструкция должна располагаться на отдельной строке.
  2. Составные инструкции оформляются ключевым словом (if, for, while) в одной строке с открывающей фигурной скобкой, списком инструкций, сдвинутым на одну табуляцию, и закрывающей фигурной скобкой на отдельной строке.
  3. После ключевого слова (if, for, while) перед открывающей фигурной скобкой должен быть пробел.
  4. Все инструкции (if, for, foreach, while, do – wile, switch, try – catch, try – finally, try – catch - finally) должны брать в фигурные скобки блок внутренних инструкций, даже если внутренняя инструкция всего одна.
  5. После каждой инструкции должна обязательно идти точка с запятой. При этом между инструкцией и точкой с запятой пробел не ставится.
  6. После закрывающей фигурной скобки блока инструкций точка с запятой не ставится.

if

// Верно

 

if (Condition) {

      DoSomething1();

      DoSomething2();

}

 

if (Condition) {

      DoSomething1();

}

 

// Неверно

 

if (Condition){

      DoSomething1();

      DoSomething2();

}

 

if (Condition)

{

      DoSomething1();

      DoSomething2();

}

 

if (Condition)

      DoSomething1();

 

if (Condition) DoSomething1();

 

if (Condition)

      {

      DoSomething1();

      DoSomething2();

      }

if – else

// Верно

 

if (Condition) {

      DoSomething1();

      DoSomething2();

} else {

      DoSomething3();

      DoSomething4();

}

 

if (Condition) {

      DoSomething1();

} else {

      DoSomething2();

}

 

// Неверно

 

if (Condition) {

      DoSomething1();

      DoSomething2();

} else

      DoSomething3();

 

if (Condition)

{

      DoSomething1();

      DoSomething2();

}

else

{

      DoSomething3();

      DoSomething4();

}

if – else – if

// Верно

 

if (Condition1) {

      DoSomething1();

      DoSomething2();

} else

if (Condition2) {

      DoSomething3();

      DoSomething4();

}

 

if (Condition1) {

      DoSomething1();

} else

if (Condition2) {

      DoSomething2();

}

 

// Неверно

 

if (Condition) {

      DoSomething1();

      DoSomething2();

} else

      DoSomething3();

 

if (Condition)

{

      DoSomething1();

      DoSomething2();

}

else

{

      DoSomething3();

      DoSomething4();

}

 

for

// Верно

 

for (Initialization; Condition; Update) {

      DoSomething1();

      DoSomething2();

}

 

for (Initialization; Condition; Update) {

      DoSomething1();

}

 

// Неверно

 

for (Initialization; Condition; Update)

{

      DoSomething1();

      DoSomething2();

}

 

for (Initialization; Condition; Update)

      DoSomething1();

 

for (Initialization; Condition; Update)

{

      DoSomething1();

      DoSomething2();

}

foreach

// Верно

 

foreach (Condition) {

      DoSomething1();

      DoSomething2();

}

 

foreach (Condition) {

      DoSomething1();

}

 

// Неверно

 

foreach (Condition){

      DoSomething1();

      DoSomething2();

}

 

foreach (Condition)

      DoSomething1();

 

foreach (Condition) {

{

      DoSomething1();

      DoSomething2();

}

 

while

// Верно

 

while (Condition) {

      DoSomething1();

      DoSomething2();

}

 

while (Condition) {

      DoSomething1();

}

 

// Неверно

 

while (Condition)

{

      DoSomething1();

      DoSomething2();

}

 

while (Condition) DoSomething1();

 

while (Condition)

DoSomething1();

do – while

// Верно

 

do {

      DoSomething1();

      DoSomething2();

}

while (Condition);

 

do {

      DoSomething1();

}

while (Condition);

 

// Неверно

 

do

{

      DoSomething1();

      DoSomething2();

}

while (Condition);

 

do

{

      DoSomething1();

} while (Condition);

 

do {

      DoSomething1();

} while (Condition);

switch

// Верно

 

switch (Condition) {

case 1:

case 2:

            DoSomething1();

            break;

      case 3:

            DoSomething2();

            DoSomething3();

            break;

      default:

            DoSomething4();

            break;

}

 

// Неверно

 

switch (Condition)

{

case 1:

case 2:

            DoSomething1();

            break;

      case 3:

            DoSomething2();

            DoSomething3();

            break;

      default:

            DoSomething4();

            break;

}

 

switch (Condition) {

case 1:

case 2: DoSomething1();

            break;

      case 3:

            DoSomething2();

            DoSomething3();

            break;

      default:

            DoSomething4(); break;

}

try – catch

// Верно

 

try {

      DoSomething1();

      DoSomething2();

}

catch {

      DoSomething3();

}

 

try {

      DoSomething1();

}

catch (e) {

      DoSomething2();

}

 

// Неверно

 

try

{

      DoSomething1();

      DoSomething2();

}

catch

{

      DoSomething3();

}

 

try {

      DoSomething1();

} catch (e) {

      DoSomething2();

}

try – finally

// Верно

 

try {

      DoSomething1();

      DoSomething2();

}

finally {

      DoSomething3();

}

 

// Неверно

 

try

{

      DoSomething1();

      DoSomething2();

}

finally {DoSomething3();}

 

try {

      DoSomething1();

} finally {

      DoSomething2();

}

try – catch - finally

// Верно

 

try {

      DoSomething1();

      DoSomething2();

}

catch {

      DoSomething3();

}

finally {

      DoSomething4();

}

 

try {

      DoSomething1();

}

catch (e) {

      DoSomething2();

}

finally {

      DoSomething3();

}

 

// Неверно

 

try

{

      DoSomething1();

      DoSomething2();

}

catch

{

      DoSomething3();

}

finally

{

      DoSomething4();

}

 

try {

      DoSomething1();

} catch ( e ) {

      DoSomething2();

} finally {

      DoSomething3();

}

Строки

  1. Все строки констант, которые не подлежат локализации, пишутся в одинарных кавычках ('').
  2. Все строки констант, которые подлежат локализации, пишутся в двойных кавычках ("").
  3. Если строка не подлежит локализации и её длина выходит за 80 символов, то она должна быть разбита на части с использованием оператора конкатенации (+), и для неё должен быть выполнен перенос на новую строку.
Если строка подлежит локализации и её длина выходит за 80 символов, то её разбиение на несколько строк запрещено.
© 2002-2012 Terrasoft
Дизайн: ISD Group