From In-Portal Developers Guide

Revision as of 19:30, 5 November 2010 (view source) Alex (Talk | contribs) (дополнение) ← Previous diff

Revision as of 19:40, 5 November 2010 (view source) Alex (Talk | contribs) m (Правила Оформления Программного Кода moved to Основные правила программирования: more Russian name) Next diff →

---

Revision as of 19:40, 5 November 2010

Contents 1 Цель 2 Форматирование PHP файлов 3 Отступы PHP в файлах 4 Назначение имён 5 Классы 6 Файлы 7 Функции и методы 8 Переменные 9 Константы 10 Префиксы 11 Фразы 12 Поля таблиц 13 Переменные конфигурации 14 Почтовые извещения 15 Добавление колонок в таблицу 15.1 Использование слова NULL 15.2 Использование слова UNSIGNED 16 NADO NAPISAT:

Цель

Правильные стандарты в программировании важны при разработке любого проекта, а тем более когда над проектом одновременно работают несколько разработчиков. Наличие стандарта программирования позволяет гарантировать высокое качество кода, меньшее количество ошибок и лёгкость его поддержки в дальнейшем.

Форматирование PHP файлов

В файлах, содержащих только PHP код, писать закрывающий тэг ("?>") не надо. Этого не требует сам PHP. Если не писать закрывающий тэг, то случайно оставленный в конце файла пробел не попадёт в поток вывода (output). Все файлы, содержащие PHP код должны быть сохранены в кодировке UTF-8.

Отступы PHP в файлах

Нужно использовать 1 табулятор (tab). Использовать пробелы (space) для создания отступов запрещается.

Назначение имён

Классы

Названия классов выбираются в зависимости от решаемых ими задач. Нужно выбрать наиболее подходящее название, раскрывающее суть класса. Названия классов могут содержат только латинские буквы и цифры. Цифры использовать можно, но не рекомендуется. Если название класса состоит больше чем из одного слова, то первая буква каждого следующего слова должна быть заглавной. Каждое слово в названии класса должно быть в единственном числе. Первая буква в названии класса всегда должна быть заглавной. Несмотря на это классы, являющиеся частью K4 могут начинаться с прописной (маленькой) буквы "k". Иерархия классов также отражается на их именах, каждый уровень отделяется заглавной буквой. Если класс переписан (extended), то первой буквой в названии переписанного класса должна быть "E" (E - extends).

Ниже приведены примеры допустимых имён классов:

UserEventHandler
EUserEventHandler
UserTagProcessor
UserHelper

Файлы

В названиях файлов разрешается использовать только прописные (маленькие) латинские буквы, цифры, подчёркивания ("_") и тире ("-"). Использовать пробелы запрещается. Каждый файл, содержащий PHP код должен иметь расширение ".php". Каждое слово в названии файла, содержащего объявление PHP класса должно быть в единственном числе. Если PHP файл содержит объявление класса, то название класса должно быть отражено в названии файла. Для получения названия файла из названия класса следует использовать следующий алгоритм (исходная строка это название класса):

1. поставить символ подчёркивания ("_") между словами;
2. заменить следующие слова на их сокращения:
   • EventHandler -> eh;
   • TagProcessor -> tp;
3. перевести все буквы в нижний регистр;
4. добавить расширение файла ".php".

Ниже приведены примеры допустимых имён файлов, содержащих классы из предыдущего примера:

users/user_eh.php
users/е_user_eh.php
users/user_tp.php
users/user_helper.php

Функции и методы

Названия функций выбираются в зависимости от решаемых ими задач. Нужно выбрать наиболее подходящее название, раскрывающее суть функции. Названия функций могут содержать только латинские буквы и цифры. Подчёркивания использовать нельзя. Цифры использовать можно, но не рекомендуется. Названия функций должно начинаться с прописной (маленькой) буквы. Если функция (метод объекта) является обработчиком события или тэга, то первая буква в её названии должна быть заглавной. Если имя функции состоит из больше чем одного слова, то первая буква каждого следующего слова должна быть заглавной. Такой способ также называют "венгерской нотацией" (camelCase). Для улучшения восприятия кода названия функций должны быть информативными (verbose) насколько это возможно.

Ниже приведены примеры допустимых названий функций:

setRequiredFields()
getElementById()
widgetFactory()
_privateMetod()
OnRegisterUser(&$event) - обработчик события
IterateGridFields($params) - обработчик тэга

Названия методов, объявленных используя ключевые слова "private" или "protected" (доступно только в PHP5) должны начинаться с одного символа подчёркивания ("_"). Этот случай является единственным допустимым применением символа подчёркивания в названиях методов. Название метода не должно начинаться с 2-х подчёркиваний (напр. "__restrictedMethodName"), т.к. могут возникнуть проблемы при использовании (и переходе на) PHP5. Названия методов, объявленных при помощи ключевого слова "public" никогда не должны начинаться с символа подчёркивания. Объявление функций в глобальном пространстве имён (global scope), т.е. "плавающих функций" разрешено, но не рекомендуется. Лучше всего объединять такие функции в статические классы.

Переменные

Названия переменных могут содержать только латинские буквы и цифры. При назывании локальных переменных методов можно также использовать символ подчёркивания ("_"). Несмотря на то, что можно использовать цифры в названии переменной, но этого делать не рекомендуется.

В названии локальных переменных в методах все буквы должны быть прописными (маленькими). Если название переменной содержит больше одного слова, то перед каждым следующим словом надо ставить символ подчёркивания. Ниже приведены примеры допустимых названий локальных переменных:

$object
$local_variable
$user_is_validated

Название атрибутов класса, объявленных с использованием ключевых слов "private" или "protected" (только в PHP5) должно начинаться с одного символа подчёркивания. Этот случай является единственным допустимым применением символа подчёркивания в названиях атрибутов класса. Атрибуты класса, объявленные используя ключевое слово "public" (только в PHP5) никогда не должны начинаться с символа подчёркивания.

Названия атрибутов класса, также как и названия функций, должны начинаться с прописной (маленькой) буквы и следовать "венгерской нотации" (camelCase). Для улучшения восприятия кода названия переменных и атрибутов классов должны быть информативными (verbose) насколько это возможно.

Краткие названия переменных, напр. как "$i" и "$n" запрещены к использованию за исключением небольших циклов. Если цикл содержит более чем 20 строк кода, то переменная, используемая в качестве индекса цикла должна иметь более описательное название.

Константы

Названия констант могут состоять из латинских букв, цифр и символов подчёркивания ("_"). Все буквы, использованные в названиях констант должны быть строчными (большими). Для улучшения читабельности, слова в названиях констант должны быть разделены символом подчёркивания. Например, название ORDER_STATUS_INCOMPLETE разрешено, а название ORDERSTATUS_INCOMPLETE запрещено. Константы должны быть заданы только в файле constants.php (для PHP4) или в классах, используя ключевое слово "const" (для PHP5).

Префиксы

Названия префиксов может состоять только из прописных (маленьких) латинских букв и тире ("-"). Если название префикса состоит более, чем из одного слова, то перед каждым последующим словом нужно ставить тире. Это является единственным допустимым применением тире в названии префикса. Каждое слово в названии префикса должно быть в единственном числе. Из соображений информативности кода не надо сокращать названия префиксов до 1-2 символов, т.к. их названия должны быть в последствии понятны не только тем, кто их придумал. Префиксы sub-items, для наглядности, должны содержать в названии свой ParentPrefix:

главный префикс	префикс "ребёнка"
user	user-image
theme	theme-file

В таком случае префикс "ребёнка" должен быть отделён от главного префикса при помощи тире. Название префиксов, которые используются только для клонирования должно начинаться с решётки ("#").

Фразы

Название фразы может состоять из латинских букв, чисел и символов подчёркивания ("_"). Название фразы состоит из трёх частей:

• префикс местоположения;
• префикс места применения;
• краткий текст фразы.

Все компоненты названия фразы объединяются используя символ подчёркивания ("_"). Это является единственным допустимым применением символа подчёркивания в названии фразы. Ниже приведены примеры всех возможных префиксов фраз:

• префикс местоположения:

Используемый префикс	Место применения
la	в административной консоли
lu	на Front-End

• префикс места применения:

Используемый префикс	Место применения
title	заголовок страницы
tab	название вкладки
section	подсекция
ToolTip	кнопка на панели инструментов (полный текст)
ShortToolTip	кнопка на панели инструментов (краткий текст)
btn	текст на кнопке
col	колонка в списке (grid column)
fld	поле на форме
config	поле в списке конфигурационных переменных
event	название почтового извещения
error	текст сообщения об ошибке
msg	информативное сообщение для пользователя
opt	опция в dropdown, radio buttons, checkboxes
text	просто тест, тоже самое, если не использовать префикс
fck	FCKEditor (начиная с Core v 4.3.2)

В кратком тексте фразы первая буква каждого слова должна быть заглавной (большой). В некоторых случаях это правило можно не соблюдать, напр. в названии фраз для почтовых извещений. Ниже приведены примеры допустимых названий фраз:

пример	описание
lu_btn_OK	Название фразы на кнопке OK на Front-End.
la_config_MaxCategoryCount	Название фразы для переменной конфигурации.
la_fld_CategoryName	Название фразы перед полем на форме редактирования.
la_event_link.modify.pending	Название фразы перед почтовым извещением LINK.MODIFY.PENDING в административной консоли.
la_text_SamplePhrase	Просто текст на странице, который не возможно классифицировать.
la_msg_SessionExpired	Сообщение о завершении сессии пользователя.

Если одновременно существуют фразы, в которых одно и тоже слово указано в разных падежах, то название падежа требуется указать в названии самой фразы, напр. "lu_HotelNominativeCase5" (см. Grammatical case).

Поля таблиц

Названия полей таблиц выбираются в зависимости от хранимых в них данных. Названия полей могут содержат только латинские буквы и цифры. Цифры использовать можно, но не рекомендуется. Если название поля состоит больше чем из одного слова, то первая буква каждого следующего слова должна быть заглавной. Каждое слово в названии поля должно быть в единственном числе. Первая буква в названии поля всегда должна быть заглавной. Ниже приведены примеры допустимых названий полей:

Age
TotalAmount
UserRight

Переменные конфигурации

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

MaxAllowedUsers
LastOrderNumber
UseHitCounter

Почтовые извещения

Название почтового извещения может содержать только заглавные латинские буквы и точки ("."), напр. "LINK.APPROVE". Каждое слово в названии почтового извещения должно быть в единственном числе. Точка используется в качестве разделителя слов (если название состоит из нескольких слов). При формировании названия нового почтового извещения рекомендуется придерживаться следующих шагов:

1. пишется название того объекта, с которым будет работать данное почтовое извещение (напр. LINK, ORDER, USER или ARTICLE);
2. ставиться символ разделителя, т.е. точка;
3. пишется название действия, которое выполняется над ранее указанным объектом (напр. APPROVE, ADD, SUBSCRIBE или DO.STUFF).

Добавление колонок в таблицу

При добавлении колонок в таблицы следует придерживаться следующих правил в указании опций колонок исходя из содержания будущей колонки:

• сумма (деньги) - тип DECIMAL(10,2) и NOT NULL
• дата (timestamp) - тип INT(11) и NULL
• короткий текст (имя/фамилия) - VARCHAR(255) и NOT NULL
• текст средней длинны (описание, от 255 байт и до 64KB) - TEXT и NULL
• длинный текст (описание, от 64KB и до 4MB) - LONGTEXT и NULL

В следующих случаях нужно всегда ставить INDEX на колонку:

• колонка содержит дату;
• колонка содержит статус записи, напр. Active/Disabled;
• колонка указывает на то, что запись основная, т.е. IsPrimary;
• по колонке будет делаться сортировка и колонка цифровая, напр. Order, Priority;
• по колонке может быть сделать JOIN;
• колонка является ForeignKey.

Использование слова NULL

Если, и только если, требуется знать факт отсутствия значения в колонке, то её надо создавать, как NULL. Во всех остальных случаях колонка должна быть NOT NULL.

Использование слова UNSIGNED

Если присутствует 100% уверенность в том, что в колонке не может быть отрицательных значений, то колонку нужно делать UNSIGNED. Колонки, где храниться timestamp нельзя делать UNSIGNED в тех случаях, когда

• в колонке с датой может быть дата меньше 1 января 1970 года;
• в колонке находиться только время (без даты).

NADO NAPISAT:

1. CVS Comments with Task #, single commit with 1 task

2. Nado krasivo otformatirovat