In-Portal Developers Guide

This is a wiki-based Developers Guide for In-Portal Open Source CMS. The purpose of this guide is to provide advanced users, web developers and programmers with documentation on how to expand, customize and improve the functionality and the code the In-Portal software. Please consider contributing to our documentation writing effort.

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

From In-Portal Developers Guide

Jump to: navigation, search
(Фразы: дополнение)
Current revision (16:18, 28 February 2009) (view source)
m (1 версия)
 

Current revision

Стандарты в программировании Стандарты в программировании
Статьи в этой категории

Contents

Классы

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

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

UserEventHandler
EUserEventHandler
UserTagProcessor
UserHelper
Image:Infobox Icon.gif Имена классов, определённых в коде, который использует 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:

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

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

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

Фразы

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

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

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

  • префикс местоположения:
Используемый префикс Место применения
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 Сообщение о завершении сессии пользователя.
Image:Infobox Icon.gif Нельзя использовать фразы и в административной консоли и на 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).