то ждем ваше обращение в нашей службе тех поддержки.
Правила оформления кода (Coding Standards PHP, SQL, JavaScript)
1. Код должен без проблем печататься на бумаге. Таким образом, все, что выходит за границу 80 символов, необходимо переносить на следующие строки, используя правила переноса строки:
· переносить можно после запятой или перед оператором;
· переносимая строка должна быть сдвинута относительно верхней на один символ табуляции;
· переносы должны быть в стиле 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 ) ){
}
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 ) ){
}
Очень сложные инструкции рекомендуется разбивать на несколько более простых.
Например,
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" ){
}
}
3. Для форматирования отступов в коде нужно использовать табуляцию. Все блоки должны выделяться отступами одинаковой величины, 4-х символьными. Использование пробелов запрещено по следующим причинам:
· используется один символ вместо нескольких;
· в случае смешивания пробелов и табуляции текст будет "прыгать", разрушая форматирование.
4. Для вертикального форматирования кода необходимо использовать пустые строки, которые помогают разбивать код приложения на логические сегменты. Несколькими строками могут отделяться секции в исходном файле. Одной пустой строкой отделяются друг от друга методы, логические секции внутри метода для более удобного чтения.
5. Пробелами должны быть разделены все символы, операции и идентификаторы [+,-,*,/,(,),{,},=,==,!=,&,&&, |, || и пр.]
6. Подчиненный код должен быть сдвинут от главного ровно на один символ табуляции. Подчиненный код не может находиться на той же строке, что и главный.
Пример:
не правильно писать так
if( $a == 0 ){ $a = 10;
$b = 1; }
правильно писать так
if( $a == 0 ){
$a = 10;
$b = 1;
}
7. Имена идентификаторов должны быть самодокументируемыми.
8. Имена идентификаторов должны быть полными английскими словами (без сокращений), с исключением, описанным в п.9.
9. Венгерская нотация (например, lpcszWinCaptn) должна использоваться только при одном условии: если весь код оформлен с применением венгерской нотации.
Рекомендуемые префиксы:
|
Префикс |
Сокращение от |
Смысл |
Пример использования |
|
Префиксы типов данных |
|||
|
s |
string |
Строка |
$sClientName |
|
sz |
zero-terminated string |
строка, ограниченная нулевым символом |
$szClientName |
|
n, i |
int |
целочисленная переменная |
$nSize, $iSize |
|
l |
long |
длинное целое |
$lAmount |
|
b |
boolean |
булева переменная |
$bIsEmpty |
|
ar |
array |
массив |
$arDimensions |
|
ob |
object |
объект |
$obFactory |
|
t, dt |
time, datetime |
время, дата и время |
$tDelivery, $dtDelivery |
|
p |
pointer |
указатель |
$pBox |
|
r |
reference |
ссылка |
$rBoxes |
|
h |
handle |
дескриптор |
$hWindow |
|
m_ |
member |
переменная-член |
$m_sAddress |
|
g_ |
global |
глобальная переменная |
$g_nSpeed |
|
C |
class |
класс |
CString |
|
T |
type |
тип |
TObject |
|
I |
interface |
интерфейс |
IDispatch |
|
V |
void |
отсутствие типа |
vReserved |
|
Префиксы к типовым объектам |
|||
|
db |
database result |
объект класса CDBResult |
$dbResult |
|
frm |
Form |
Форма |
$frmLogin |
|
frame |
Frame |
Фрейм |
$frameWeatherData |
|
dlg |
dialogue form |
диалоговая форма |
$dlgRightsNotifier |
|
menu |
Menu |
Меню |
$menuCatalog |
|
pmenu |
PopupMenu |
Контекстное меню |
$pmenuDatasetActions |
|
lb |
Label |
Метка |
$lbAuthArea |
|
ed |
TextField |
Текстовое поле |
$edSearch |
|
btn |
Button |
Кнопка |
$btnConfirmData |
|
chk |
CheckBox |
Чекбокс |
$chkSquard |
|
radio |
RadioButton |
Кнопка выбора |
$radioManCityValue |
|
slct |
Select |
Список выбора |
$slctLanguages |
|
img |
Image |
Изображение |
$imgPageBackground |
|
scroll |
ScrollBox |
Скролл |
$scrollPicturesFrame |
|
timer |
Timer |
Счетчик времени |
$timerDataOverset |
Если класс различается для разных СУБД и соответственно имеет базовый класс с общими для всех СУБД методами, то этот базовый класс должен в своем имени после символа "C" содержать символы "All".
Пример: CAllSaleAffiliate.
10. Именование переменных. Первое логическое слово должно начинаться с маленькой буквы, остальные логические слова - с большой (стиль Кэмел).
Например: $testCounter, $userPassword
11. Именование методов и функций.Каждое логическое слово должно начинаться с заглавной буквы (стиль Паскаль).
Например: CountVariable, ChangeUserPassword
12. Именование членов-переменных и методов класса в контексте доступа к ним осуществляется следующим образом:
· члены-переменные и методы, которые являются приватными и к которым не может обращаться никто, кроме самого модуля (т.е. ни публичная часть, ни другие модули), должны начинаться с двух символов подчеркивания.
Например, __CheckEmail, __arData;
· члены-переменные и методы, которые являются внутренними и к которым могут обращаться только модули продукта (т.е. публичная часть не может), должны начинаться с одного символа подчеркивания.
Например, _CheckEmail, _arData;
· остальные методы и члены-переменные считаются публичными.
13. Константы дложны писаться большими буквами и иметь префикс «VR_».
Например, VR_ROOT, VR_FILE_PERMISSIONS.
14. Локальное имя всегда лучше имени, определенного на уровне расположенном иерархически выше (относительно глобальным). При написании кода необходимо пользоваться условием: всякая глобальная переменная может быть (при желании) заменена локальной, или быть свойством объекта.
15. При написании кода запрещено использовать одинаковые имена переменных, но с разным регистром символов.
16. В каждой строчке должно присутствовать только одно выражение/операция.
Пример:
не правильно писать так
$a = $b; $b = $c; $c = $a;
правильно писать так
$a = $b;
$b = $c;
$c = $a;
17. Допустимы два написания инструкций if, else, while и т.п.:
· если тела всех частей инструкции состоят не более чем из одного выражения, то инструкция может записываться в виде
if( условие )
действие1;
else
действие2;
· если тело хотя бы одной из частей состоит более чем из одного выражения, то инструкция должна записываться в виде
if( условие ){
действие1;
}
else{
действие2;
действие3;
}
При написании инструкций должно строго применяться правило форматирования подчиненности: тело инструкции должно быть сдвинуто на один символ табуляции вправо от самой инструкции. Закрывающая фигурная скобка должна находиться на отдельной строке и должна быть на одном уровне с инструкцией.
Пример:
не правильно писать так
if( $a == 0 ) $a = 10;
else{
$a = 5;
$b = 10;}
правильно писать так
if( $a == 0 ){
$a = 10;
}
else{
$a = 5;
$b = 10;
}
18. Массивы, которые записываются в несколько строк, следует форматировать следующим образом
$arFilter = array(
"key1" => "value1",
"key2" => array(
"key21" => "value21",
"key22" => "value22",
)
);
19. В сложных выражениях рекомендуется группировать операции с помощью скобок вне зависимости от того, требует это приоритет операций или нет.
Пример:
$r = $a + ( $b * $c );
20. Значения параметров по умолчанию использовать не рекомендуется, вследствие усложнения понимания кода.
21. Если функция может вернуть ошибочное значение, она его вернет. Обрабатывать надо все возможные алгоритмические ветки.
22. Функции, особенно низкоуровневые, должны не печатать сообщения об ошибках, а возвращать некое значение, указывающее на природу и содержание ошибки. Это дает возможность внешней функции предпринять какие-то корректирующие действия.
23. Если параметр не изменяется в теле функции, то он должен быть объявлен константным.
24. Если параметр изменяется в теле функции, но не передаётся на верхний уровень, то параметр должен быть объявлен параметром по значению.
25. Каждая операция SELECT, FROM, WHERE, ORDER BY, GROUP BY, HAVING должна начинаться с новой строки. Правило переноса длинной строки такое же как в PHP: новая строка с табуляцией.
Назад в раздел
Наверх