Понедельник, 19.02.2018, 22:58
Приветствую Вас Гость | RSS

Bitrix программирование

Категории раздела
Статистика



Онлайн всего: 1
Гостей: 1
Пользователей: 0
Форма входа

Правила написания исходного кода на PHP (Часть 2)

Каталог статей

Главная » Статьи » Программирование

Правила написания исходного кода на PHP (Часть 2)

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, новая строка с табуляции.



Источник: http://dev.1c-bitrix.ru/docs/php_recommendation.php
Категория: Программирование | Добавил: Shak (07.06.2010)
Просмотров: 2223 | Теги: Правила написания исходного кода на | Рейтинг: 0.0/0
Поиск

Shak © 2018
Копирование материала без указания автора и ссылки на сайт запрещается.
Если вы разместили материал у себя на сайте обязательно свяжитесь со мной shakleinserg{собака}gmail.com
Создать бесплатный сайт с uCoz