1.3. Пустые строки и пробелы
1.3.1. Пустые строки
Пустые строки помогаю разбивать код приложения на логические сегменты. Несколькими строками могут отделяться секции в исходном файле. Одной пустой строкой отделяются друг от друга методы, логические секции внутри метода для более удобного чтения.
Перед логической секцией рекомендуется вставить комментарий, в котором будет указано назначение этой секции (см. пункт 3).
1.3.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++)
Табличное форматирование с помощью символов табуляции не должно использоваться.
Пример неправильного форматирования:
$arArray = array(
"key1" => "value1",
"key2" => "value2",
);
Замечание: присутствие или отсутствие пробела после if правилами не регламентируется.
1.4. Прочее
В сложных выражениях рекомендуется группировать операции с помощью скобок вне зависимости от того, требует это приоритет операций или нет.
Пример:
$r = $a + ($b * $c);
2. Соглашение об именовании
2.1. Общие понятия
Не используйте подчеркивание для отделения слов внутри идентификаторов, это удлиняет идентификаторы и затрудняет чтение.
Старайтесь давать переменным, методам и пр. "говорящие" названия. Предпочтительно использовать имена, которые ясно и четко описывают предназначение и/или смысл сущности.
Старайтесь делать имена идентификаторов как можно короче (но не в ущерб читабельности).
2.2. Именование переменных
Первое логическое слово должно начинаться с маленькой буквы, остальные логические слова - с большой (стиль Кэмел).
Например: $testCounter, $userPassword
2.3. Именование методов и функций
Каждое логическое слово должно начинаться с заглавной буквы (стиль Паскаль).
Например: CountVariable, ChangeUserPassword
2.4. Префиксы переменных
PHP - не особо типизированый язык и в нем различаются по смыслу только три группы типов: скалярные, массивы и объекты.
Массивы следует именовать с префиксом "ar", при этом следующее логическое слово в названии начинается с большой буквы. Например, $arResult, $arModifiedUsers.
Объекты следует именовать с префиксом "ob", при этом следующее логическое слово в названии начинается с большой буквы. Например, $obElement, $obUser.
Объект класса CDBResult следует начинать с префикса "db", при этом следующее логическое слово в названии начинается с большой буквы. Например, $dbResult.
Скалярные типы следует начинать с префиксов только в том случае, если точно известно, что они имеют заданный тип.
Например в коде
$userID = $_REQUEST["var"];
$userID = IntVal($userID);
переменная идет без префикса, так как ее тип меняется по ходу выполнения программы.
В коде
$bFlag = (($aaa > 0)? True : False);
переменная идет с префиксом, так как ее тип в общем известен и не меняется.
2.5. Именование классов
Имя класса должно начинаться с буквы "C". Если класс принадлежит модулю, то дальше должно идти "фирменное" название модуля. Каждое логическое слово должно начинаться с заглавной буквы.
Пример: CIBlockElement, CIBlockType, CSaleAffiliate.
Если класс различается для разных СУБД и соответственно имеет базовый класс с общими для всех СУБД методами, то этот базовый класс должен в своем имени после символа "C" содержать символы "All".
Пример: CAllSaleAffiliate.
2.6. Доступность членов-переменных и методов класса
Так как у нас нет других методов организации видимости и доступности членов-переменных и методов классов, то следует применять следующие правила:
· члены-переменные и методы, которые являются приватными и к которым не может обращаться никто, кроме самого модуля (т.е. ни публичная часть, ни другие модули), должны начинаться с двух символов подчеркивания. Например, __CheckEmail, __arData. Эти методы не описываются в документации и могут быть изменены без обеспечения совместимости;
· члены-переменные и методы, которые являются внутренними и к которым могут обращаться только модули продукта (т.е. публичная часть не может), должны начинаться с одного символа подчеркивания. Например, _CheckEmail, _arData. Эти методы не описываются в публичной документации (но хорошо бы описать во внутренней) и могут быть изменены без обеспечения совместимости только после уведомления всех сотрудников;
· остальные методы и члены-переменные считаются публичными, должны быть описаны в документации и не могут быть изменены без обеспечения совместимости.
2.7. Именование констант
Константы дложны писаться большими буквами и иметь префикс «BX_».
Например, BX_ROOT, BX_FILE_PERMISSIONS.
3. Комментарии
Для пояснения назначения класса или метода необходимо размещать комментарий перед объявлением этого класса или метода.
Необходимо избегать очевидных комментариев типа
$i = $i + 1; // добавить к i единицу
Следует добавлять комментарий о назначении классов и методов к каждому публичному классу или методу.
Перед логическими секциями кода желательно добавлять комментарии о том, что данная секция будет делать.
Комментарии должны быть только на английском языке.
4. Идиомы программирования
4.1. Общее понятие
В любом языке программирования существуют так называемые идиомы, то есть повсеместно применяемые способы использования тех или иных конструкций. Например, в языке PHP к таким идеомам можно отнести форму записи цикла по элементам массива
for ($i = 0, $cnt = count($arArray); $i < $cnt; $i++)
{
}
или
foreach ($arArray as $key => $value)
{
}
Использование идиом позволяет читающему пропускать очевидные фрагменты кода и сосредоточиться на содержательных вещах, а также находить в коде нужные фрагменты по характерным (идиоматическим) конструкциям.
Необходимо стараться использовать общепринятые конструкции, а не изобретать свои собственные.
Пример:
код
reset($arHashLink);
while(list($hash, $arData)=each($arHashLink))
{
}
лучше переписывать в таком виде
foreach ($arHashLink as $hash => $arData)
{
}
4.2. Примеры идиом
Идиома оператора "?"
$res = ($bTrue? "True" : "False");
5. SQL запросы
Каждая операция SELECT, FROM, WHERE, ORDER BY, GROUP BY, HAVING должна начинаться с новой строки.
Правило переноса длинной строки такое же как в PHP, новая строка с табуляции.