Структурирование текста

1. Длина строки

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

2. Правила переноса строки

   Если длина строки превышает 120 символов, то необходимо пользоваться следующими правилами переноса:

   • переносить можно после запятой или перед оператором;
   • переносимая строка должна быть сдвинута относительно верхней на один символ табуляции;
   • переносы должны быть в стиле UNIX.

   Пример 1: для строки

   $arAuthResult = $USER->ChangePassword($USER_LOGIN, $USER_CHECKWORD, $USER_PASSWORD, $USER_CONFIRM_PASSWORD, $USER_LID);

   допустимым будет следующий вариант переноса

   $arAuthResult = $USER->ChangePassword($USER_LOGIN, $USER_CHECKWORD,
        $USER_PASSWORD, $USER_CONFIRM_PASSWORD, $USER_LID);

   Пример 2: для строки

   if(COption::GetOptionString("main", "new_user_registration", "N")=="Y" && $_SERVER['REQUEST_METHOD']=='POST' &&$TYPE
   =="REGISTRATION" && (!defined("ADMIN_SECTION") || ADMIN_SECTION!==true)) 

   допустимым будет следующий вариант переноса

   if (COption::GetOptionString("main", "new_user_registration", "N") == "Y"
        && $_SERVER['REQUEST_METHOD'] == 'POST' && $TYPE == "REGISTRATION"
        && (!defined("ADMIN_SECTION") || ADMIN_SECTION !== true)
   

3. Пробелы и табуляция

   Для форматирования отступов в коде нужно использовать табуляцию. Использование пробелов запрещено. Причины:

   • в случае использования табуляции каждый может настроить в своем редакторе желаемый отступ;
   • используется один символ вместо нескольких;
   • в случае смешивания пробелов и табуляции текст будет прыгать, разрушая форматирование.
4. Форматирование подчиненности

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

   Пример:

   function func()
   {
        if (condition)
        {
             while (condition2)
             {
   
             }
         }
   }

5. Правила расстановки фигурных скобок

   Открывающая скобка должна ставиться под соответствующим оператором и на одном отступе с ним. Закрывающая скобка должна ставится под соответствующей открывающей.

   Пример:

   if ($condition)
   {
      ...
   }
   

6. Использование тернарного оператора "?:"

   Условие следует заключать в скобки, тем самым отделяя его от остального кода. По возможности, действия, производимые по условию, должны быть простыми функциями. Если весь блок ветвления плохо читается, то стоит заменить его на if/else.

   Пример: ((условие) ? funct1() : func2());

Инструкции, выражения

1. Выражения

   Желательно, чтобы в каждой строчке присутствовало только одно выражение.

   Пример. Неправильно писать так:

   $a = $b; $b = $c; $c = $a;

   Правильно писать так

   $a = $b;
   $b = $c;
   $c = $a;
   

2. Инструкции "if", "else", "while" и т.п.

   Допустимы два вида написания инструкций:

   • если тела всех частей инструкции состоят не более чем из одного выражения, то инструкция может записываться в виде

     if (условие) 
         действие1; 
     else 
         действие2;

   • если тело хотя бы одной из частей состоит более чем из одного выражения, то инструкция должна записываться в виде

     if (условие) 
     {
         действие1; 
     } 
     else

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

   
   

   Пример. Неправильно писать так:

   if ($a == 0) $a = 10;
   else{
   $a = 5;
   $b = 10;}
   

   Правильно писать так:

   if ($a == 0)
   {
     $a = 10;
   }
   else
   {
     $a = 5;
     $b = 10;
   }
   

3. Сложные инструкции

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

    if(COption::GetOptionString("main", "new_user_registration", "N")=="Y" && $_SERVER['REQUEST_METHOD']=='POST' &&
        $TYPE=="REGISTRATION" && (!defined("ADMIN_SECTION") || ADMIN_SECTION!==true))
   

   Можно записать как:

   if (COption::GetOptionString("main", "new_user_registration", "N") == "Y"
        && $_SERVER['REQUEST_METHOD'] == 'POST' && $TYPE == "REGISTRATION"
        && (!defined("ADMIN_SECTION") || ADMIN_SECTION !== true))
   {
   }
   

   Очень сложные инструкции рекомендуется разбивать на несколько более простых. Например,

   if((!(defined("STATISTIC_ONLY") && STATISTIC_ONLY && substr($APPLICATION->GetCurPage(), 0,
        strlen(BX_ROOT."/admin/"))!=BX_ROOT."/admin/")) && COption::GetOptionString("main", "include_charset", "Y")=="Y"
        && strlen(LANG_CHARSET)>0)
   

   Можно записать так:

   $publicStatisticOnly = False;
   if (defined("STATISTIC_ONLY")
     && STATISTIC_ONLY
     && substr($APPLICATION->GetCurPage(), 0, strlen(BX_ROOT."/admin/")) != BX_ROOT."/admin/")
   {
        $publicStatisticOnly = True;
   }
   if (!$publicStatisticOnly && strlen(LANG_CHARSET) > 0
        && COption::GetOptionString("main", "include_charset", "Y") == "Y")
   {
   }

   или так:

   if (!defined("STATISTIC_ONLY") || ! STATISTIC_ONLY
     || substr($APPLICATION->GetCurPage(), 0, strlen(BX_ROOT."/admin/")) == BX_ROOT."/admin/")
   {
     if (strlen(LANG_CHARSET) > 0 && COption::GetOptionString("main", "include_charset", "Y") == "Y")
     {
     }
   }
   

4. Форматирование массивов Массивы, которые записываются в несколько строк, следует форматировать следующим образом:

   $arFilter = array(
     "key1" => "value1",
     "key2" => array(
         "key21" => "value21",
         "key22" => "value22",
     )
   ); 

Пустые строки и пробелы

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

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

   Перед логической секцией рекомендуется вставить комментарий, в котором будет указано назначение этой секции (см. Комментарии).

2. Пробелы

   После запятой должен быть пробел. После точки с запятой, если она не последняя в строке (например, в инструкции for), должен быть пробел. Перед запятой или точкой с запятой пробелы не ставятся. Все операторы должны быть отделены пробелом от операндов с обеих сторон. Замена пробела символом табуляции не допускается.

   Пояснения:
   • Один пробел используется в объявлении методов после запятой, но не перед скобками: TestMethod($a, $b, $c);

     Примеры неправильного использования:

     • TestMethod($a,$b,$c);
     • TestMethod( $a, $b, $c );
   • Так же одиночный пробел используют для выделения операторов: $a = $b * $c / $d;

     Пример неправильного использования: $a=$b*$c/$d;

   • Также пробелы используются при форматировании циклов:for ($i = 0; $i < 10; $i++).

     Пример неправильного использования: for($i=0;$i<10;$i++)

Прочее

В сложных выражениях рекомендуется группировать операции с помощью скобок вне зависимости от того, требует это приоритет операций или нет. Пример: $r = $a + ($b * $c);