From In-Portal Developers Guide

Revision as of 20:22, 5 November 2010

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

PHP файлы

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

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

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

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

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

Классы

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

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

UserEventHandler
EUserEventHandler
UserTagProcessor
UserHelper

Имена классов, определённых в коде, который использует Kernel4, но не является его частью не могут начинаться с буквы "k".

Файлы

В названиях файлов разрешается использовать только прописные (маленькие) латинские буквы, цифры, подчёркивания ("_") и тире ("-"). Использовать пробелы запрещается. Каждый файл, содержащий 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:

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

Названия Special формируются по таким-же правилам.

Фразы

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

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

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

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

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

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

Нельзя использовать фразы и в административной консоли и на Front-End одновременно (тип фразы "Both" устарел). Если требуется использовать фразу из Admin на Front-End (или наоборот), то надо создать копию и переименовать la_ в lu_ (или наоборот).

Если одновременно существуют фразы, в которых одно и тоже слово указано в разных падежах, то название падежа требуется указать в названии самой фразы, напр. "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.

В каждой таблице должен быть основной ключ (primary key). Этот ключ всегда должен состоять из одной цифровой колонки и не должен быть UNSIGNED.

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

Все колонки типов TINYTEXT, TEXT, LONGTEXT должны быть NULL без DEFAULT значения (требование в MySQL5).

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

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

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

Работа с репозиторием кода

В скором будущем в In-Business появиться возможность видеть все изменённые/добавленные файлы для каждого из заданий, по которым делался commit в репозиторий. Для этого надо как минимум указывать в каждом commit комментарии ID задания, в связи с которым делается данный commit. Это не только облегчит дальнейший поиск конкретного фрагмента кода в репозитории, но и поможет быстрее определить код, изменённый для выполнения конкретного задания.

• 1 commit на одно задание, т.е. запрещается мешать изменения по 2-м или более заданиям в один commit
• каждый commit должен быть привязан к одному заданию In-Business
• к каждому commit нужно указывать комментарий вида "#NNNNN - Заголовок задания" (заголовок задания можно скопировать из dashboard).
• в случае, когда в commit комментарии нужно указать дополнительную информацию, то это можно сделать на 2-й строке и далее:

Task #344533 - Create Separate Grid for Products
1. Applied patch from http://tracker.in-portal.org/view.php?id=920 task from In-Portal Issue Tracker
2. Minor fixes