php правила именования классов

Именование классов?

Добрый день. При разработке одной системы столкнулся с вопросом именования классов в сложных случаях. Проблема заключается в том, что в иерархии классов отдельный элемент не всегда имеет только одного «предка» (не только в смысле наследования («цветок наследуется от растения»), но и в более общем «цветок имеет листики»). Собственно, вопрос заключается в следующем — по какому правилу именовать данные элементы?

Несколько примеров классов, с именами которых возникает проблема (прошу прощения за дурацкие примеры):

— Лилия, наследуемая от цветка (B, наследуемый от A)

— Лепесток, который может быть только у лилии (C, который используется только в B)

— Лист, который может быть и у лилии, и у цветка вообще (D, который используется и в B, и в A)

— Тычинка, которая может быть и у лилии, и у мака, но необязательно она есть у цветка вообще (E, который используется и F (который, в свою очередь, наследуется от A), и в B, но в A он не используется)

И крайний случай: есть квартира, в которой есть какая-то красивая фигня. Лилию, в принципе, можно использовать в качестве красивой фигни. Как назвать адаптер «Лилия as Красивая фигня», чтобы он не потерялся среди всех классов (т.к. теоретически он принадлежит группе «квартира», но также зависит и от группы «цветы»)? Абстрактно — есть G, которая использует H; как назвать I, который ползволяет использовать B как H?

Заминка возникла из-за строго иерархической файловой системы и привычки называть классы a-la папки (т.е. Fuston_Http_Response_Cookie_Marked). Эта привычка как раз и не дает ответа на вопрос «как назвать интерфейс, который позволит Testing_Database_Cache_Cookies использовать посторонний класс Fuston_Http_Response_Cookie как свой собственный Testing_Database_Cache_Cookies_Cookie?».

Источник

Практическое руководство по именованию классов, функций и переменных

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

«В компьютерном программировании соглашение об именах — набор правил для выбора последовательности символов, которая будет использоваться для идентификаторов, которые обозначают переменные, типы, функции и другие объекты в исходном коде и документации», — «Википедия»

Придумывать названия сложно!

В этой статье мы сосредоточимся на методе именования (P)A/HC/LC для того, чтобы улучшить читаемость кода. Эти рекомендации можно применить к любому языку программирования, в статье для примеров кода используется JavaScript.

Что значит (P)A/HC/LC?

В этой практике используется следующий шаблон для именования функции:

Что обозначает префикс (P)?

Префикс расширяет смысл функции.

Описывает свойство или состояние текущего контекста (обычно — логическое значение).

Указывает, имеет ли текущий контекст определенное значение или состояние (обычно — логическое значение).

Отражает положительный условный оператор (обычно — логическое значение), связанный с определенным действием.

Читайте также:

Действие — это сердце функции

Действие — это глагольная часть имени функции. Это самая важная часть в описании того, что делает функция.

Получает доступ к данным немедленно (сокращение от getter для внутренних данных).

Безусловно присваивает переменной со значением A значение B.

Возвращает переменную к её начальному значению или состоянию.

Выполняет запрос данных, для которого требуется время (например, асинхронный запрос).

Удаляет что-то откуда-то.

Полностью стирает что-то. После операции сущность перестаёт существовать.

Создает новые данные из существующих. Обычно это применимо к строкам, объектам или функциям.

Обработка действия. Часто используется при именовании обратного вызова.

Контекст

Контекст — это область, с которой работает функция.

Функция — это часто действие с чем-то. Важно указать, какова её рабочая область или, по крайней мере, ожидаемый тип данных.

В итоге

Пять принципов именования переменных

В этом разделе мы предложим некоторые правила именования переменных, которые улучшат читаемость кода.

1. Следуйте S-I-D

Имя должно быть коротким (Short), интуитивно понятным (Intuitive) и описательным (Descriptive).

2. Избегайте сокращений

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

3. Избегайте дублирования контекста

Всегда удаляйте контекст из имени, если это не снижает его читабельность.

4. Отражайте в имени ожидаемый результат

5. Учитывайте единственное/множественное число

Как и префикс, имена переменных могут быть единственного или множественного числа в зависимости от того, имеют ли они одно значение или несколько.

Источник

Практическое руководство по именованию классов, функций и переменных

В компьютерном программировании соглашение об именах — набор правил для выбора последовательности символов, которая будет использоваться для идентификаторов, которые обозначают переменные, типы, функции и другие объекты в исходном коде и документации, — «Википедия»

Придумывать названия сложно!

В этой статье мы сосредоточимся на методе именования (P)A/HC/LC для того, чтобы улучшить читаемость кода. Эти рекомендации можно применить к любому языку программирования, в статье для примеров кода используется JavaScript.

Что значит (P)A/HC/LC?

В этой практике используется следующий шаблон для именования функции:

Что обозначает префикс (P)?

Префикс расширяет смысл функции.

Описывает свойство или состояние текущего контекста (обычно — логическое значение).

Указывает, имеет ли текущий контекст определенное значение или состояние (обычно — логическое значение).

Отражает положительный условный оператор (обычно — логическое значение), связанный с определенным действием.

Действие — это сердце функции

Действие — это глагольная часть имени функции. Это самая важная часть в описании того, что делает функция.

Получает доступ к данным немедленно (сокращение от getter для внутренних данных).

Безусловно присваивает переменной со значением A значение B.

Возвращает переменную к её начальному значению или состоянию.

Выполняет запрос данных, для которого требуется время (например, асинхронный запрос).

Удаляет что-то откуда-то.

Полностью стирает что-то. После операции сущность перестаёт существовать.

Создает новые данные из существующих. Обычно это применимо к строкам, объектам или функциям.

Обработка действия. Часто используется при именовании обратного вызова.

Контекст

Контекст — это область, с которой работает функция.

Функция — это часто действие с чем-то. Важно указать, какова её рабочая область или, по крайней мере, ожидаемый тип данных.

В итоге

Пять принципов именования переменных

В этом разделе мы предложим некоторые правила именования переменных, которые улучшат читаемость кода.

1. Следуйте S-I-D

Имя должно быть коротким (Short), интуитивно понятным (Intuitive) и описательным (Descriptive).

2. Избегайте сокращений

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

3. Избегайте дублирования контекста

Всегда удаляйте контекст из имени, если это не снижает его читабельность.

4. Отражайте в имени ожидаемый результат

5. Учитывайте единственное/множественное число

Как и префикс, имена переменных могут быть единственного или множественного числа в зависимости от того, имеют ли они одно значение или несколько.

6. Используйте осмысленные и произносимые имена

Источник

Правила и рекомендации по именованию

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

Кроме обязательных правил в настоящий раздел включены рекомендации, носящие необязательный характер.

База данных #

Таблицы

Обязательное правило: названия всех таблиц приложения должны начинаться с идентификатора приложения (APP_ID), отделенного символом подчеркивания.

Рекомендация: таблицы сущностей, например, для хранения сообщений в гостевой книге, стикеров, файлов и т.д., рекомендуется называть в единственном числе.

Таблица для хранения email-ов контактов.
wa_contact_emails — связь один ко многим, один контакт — несколько email

Таблицы плагинов

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

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

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

Там где это необходимо, и для большей понятности, можно добавлять к такому имени поля смысловой префикс.

Классы, методы и переменные PHP #

Наименование классов и методов

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

Именование PHP-файлов классов

Классы PHP подгружаются системой при выполнении скриптов с помощью механизма Autoload. Для того, чтобы механизм подгрузки смог найти нужный PHP-файл необходимо придерживаться определенных правил для именования файлов классов.

Обязательное правило: все файлы классов должны находиться внутри подпапки lib в каталоге приложения.

Именование классов и методов контроллеров и экшенов #

Логика приложения, живущая в слое контроллеров, организована в двухуровневую иерархию «модуль/действие» (MODULE/ACTION). Правила маршрутизации задают соответствие между URL запроса и парой модуль+действие. Т.е. каждый запрос по сути запускает выполнение определенного действия внутри определенного модуля.

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

Обязательное правило: название класса и метода для обработки запроса должны соответствовать правилам, по которым система ищет класс и метод для исполнения. Поиск производится в следующем порядке (конкатенация строк при построении названия класса производится в «горбатом» стиле без разделителей):

Если ни один класс не найден, то отдается ошибка 404.

Примеры допустимых соответствий пар модуль + действие и названий классов и методов.

Приложение myblog, модуль mail, действие не указано:

Приложение myblog, модуль mail, действие test:

Подробнее система маршрутизации рассматривается в разделах «Маршрутизация в бекенд» и «Маршрутизация во фронтенд».

Именование файлов шаблонов #

Каждый шаблон жестко привязан к конкретному действию конкретного модуля. Механизм определения шаблона для рендеринга опирается на названия модуля и действия.

Обязательное правило: для случаев, когда ACTION не был указан, правила именования шаблона зависят от типа класса экшена:

Подробнее о типах классов экшенов см. раздел «Экшены и контроллеры».

Именование глобально доступных идентификаторов (JavaScript, CSS, сессии, cookie) #

Глобально доступные идентификаторы (переменные и функции JavaScript, CSS-классы, параметры запросов, обрабатываемые классом waRequest, переменные пользовательских сессий и cookie) нужно именовать таким образом, чтобы они не приводили к конфликтам с любыми другими программными продуктами, которые могут использоваться в бекенде и фронтенде Вебасиста. Для этого в именах таких идентификаторов используйте ID вашего плагина или приложения.

Рекомендация: при написании JavaScript-кода желательно не использовать глобальные идентификаторы и оформлять код плагина с использованием замыканий.

Рекомендации по стилю форматирования PHP-кода #

Рекомендация: при разработке приложений (особенно при командной разработке), рекомендуется придерживаться единого стиля форматирования кода. Мы рекомендуем придерживаться стиля, применяемого в коде фреймворка и приложений Вебасист:

Webasyst — это CMS нового поколения, совмещающая в себе инструменты для управления сайтом и интернет-магазином с полезными приложениями для совместной работы с коллегами и взаимодействия с клиентами. Единый центр управления бизнесом через интернет.

Платформа

Магазин Webasyst

Помощь

Мы получаем и обрабатываем персональные данные посетителей сайта в соответствии с Политикой обработки персональных данных. Отправка персональных данных с помощью любой страницы сайта подразумевает согласие со всеми пунктами Политики.

Источник

PHP Code Style Conventions

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

Правила именования файлов и папок

Все названия для папок и файлов должны быть осмысленными и говорящими (не требующие дополнительного разъяснения).

Папки

Если папка хранит в себе классы, которые относятся к пространству имен (namespace), то папка именуется в соответствии с названием пространства имен (namespace).

Файлы

Если файл является файлом класса, то именуется в соответствии с названием класса.

Правила именования пространств имен, классов, методов и переменных

Все названия должны быть осмысленными и говорящими (не требующие дополнительного разъяснения).

Пространства имен

Названия пространств имен должны быть в нижнем регистре и состоять из одного слова. В случае необходимости именовать пространств имен более одного слова производится дробление на составные части, являющиеся вложенными пространствами имен.

Классы

Методы

К названиям методов применяются следующие правила:

Переменные

К названиям переменных применяются следующие правила:

Название переменной должно передавать намерения программиста

Название переменной должно сообщить, почему эта переменная существует, что она делает и как используется

Название переменной не должно быть коротким

Если переменная хранит признак, то он должен быть включен в название ( unpaidProject )

Переменные и свойства объекта должны являться существительными и называться так, чтобы они правильно читались при использовании, а не при инициализации

Плохо:

Хорошо:

Запрещены отрицательные логические названия

Плохо:

Хорошо:

Правила оформления кода

В первую очередь ставится пространство имен (namespace), которое используется (если есть). Далее пишется конструкции использования классов ( use ). В случае использования нескольких
классов одного пространства имен происходит группировка с помощью конструкции <. >. Далее идет объявление класса.

Фигурные скобки ставятся на той же строке и разделяются пробелом.

Каждая переменная должна быть объявлена на новой строке.

Условия и служебные вызовы методов разделяются переносом строки, переменные и работа с ними переносами строк не разделяются.

Внутри условий и циклов дополнительный перенос на новую строку не ставится.

Содержимое класса разделяется сверху одной пустой строкой.

Перед возвращаемым значением( return ) обязательно ставится перенос строки, если метод не состоит из единственной строки.

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

Плохо:

Хорошо:

Комментирование кода

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

Комментарии должны быть расположены перед объявлением классов, переменных и методов и быть оформлены в соответствии с PHPDoc. Комментарий перед классом должен содержать описание бизнес-логики и отражать его назначение с приведением примеров использования.

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

Правила написания кода

Везде, где имеет смысл, должнно быть прописано declare(strict_types=1);

Нельзя изменять переменные, которые передаются в метод на вход (исключение — если эта переменная объект).

Строки обрамляются одинарными кавычками. Двойные кавычки используются только, если:

Вместо лишней конкатенации используем подстановку переменных в двойных кавычках

Метод должен явно отличать нормальные ситуации от исключительных.

По умолчанию тексты исключений не должны показываться пользователю. Они предназначены для логирования и отладки. Текст исключения можно показать пользователю, если оно явно для этого предназначено.

В условном операторе должно проверяться исключительно boolean значение. В сравнении не boolean переменных используется строгое сравнение с приведением типа ( === ), автоматическое приведение и нестрогое сравнение не используются.

При использовании в условном выражении одновременно операторов И и ИЛИ обязательно выделять приоритет скобками.

Источник