Yabbi SSP

Appearance

On this page

Описание стандарта ​

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

  1. Код должен соответствовать стандартам PSR-2, PSR-4 и Symfony coding standards.

  2. Модификаторы доступа

    1. Константам классов (интерфейсов, трейтов) всегда нужно указывать модификатор доступа. Исключение - целевая версия php < 7.1.
    2. В классах не должно быть методов, которые не используются (или не требуются интерфейсом). Не нужно генерировать какие-нибудь геттеры заранее. Исключение - требование интерфейса.
    3. Модификатор доступа по умолчанию - private. Не стоит объявлять модификатор public или protected, если метод не используется в других классах (даже если планируется его использовать в будущем. Вот когда реально потребуется - модификатор доступа можно будет изменить). Исключение - требование интерфейса.

  3. Именование переменных

    1. В названии переменной нужно использовать больше одной буквы.
    2. Не стоит писать имена переменных транслитом. Исключение - аббревиатуры.
    3. Не стоит сокращать слова в названии переменных. В крайнем случае допустимы общепринятые сокращения.
  1. Кавычки
    1. По умолчанию стоит использовать одинарные кавычки. Двойные кавычки стоит использовать, если:
      • внутри строки обрабатываются переменные и методы объектов
      • в контенте строки встречаются одинарные кавычки
      • из соображений консистентности, если в рядом стоящих строчках кода используются двойные кавычки по вышеописанным причинам

  1. Формирование строк

    1. По возможности, конкатенации строк следует избегать. Формировать строку лучше используя двойные кавычки и вставку переменных прямо в строку.
    2. При вставке переменной в строку не нужно оборачивать её в фигурные скобки, за исключением случаем конфликта с другими символами строки.
    3. По возможности, вызов методов и обращения к массивам тоже следует вызывать в двойных кавычках, но тут без оборачивания в фигурные скобки уже не обойтись.

  2. Импорт классов и функций

    1. Если в коде нужно получить название какого-либо класса, следует обратиться к его статической константе class. Хардкодить название класса в виде строки не допускается. Исключений два:
      • необходимо предотвратить загрузку данного класса
      • нужно обратиться к классу не из php-кода (например в yaml-конфиге)
    2. По умолчанию все классы и функции должны быть импортированы ключевыми словами "use" и "use function" соответственно. Обращение по неймспейсу в остальных частях кода (включая phpdoc-блоки) не допускается. Исключение - не php-файлы (например в yaml-конфиг).
    3. Классы должны быть импортированы все без исключения, включая классы из глобального пространства имен (например \Exception).
    4. Функции из глобального пространства имен можно не импортировать.
    5. В случае возникновения конфликта имен стоит создать алиасы, состоящие из неймспейса + имени класса. Количество сегментов неймспейса, которые будут задействованы для формирования алиаса, определяются программистом в каждом конкретном случае. Например для Guzzle\Http\Client можно создать алиас как HttpClient, так GuzzleHttpClient, все зависит от контекста использования, например второй случай предпочтительнее, если в коде используется http-клиент другого вендора.
    6. Если название импортированного класса совпадает с названием класса из глобального пространства имен, то для него в любом случае стоит создать алиас, даже если одноименный класс из глобального пространства имен в данном файле не используется и конфликта имен не возникает. Например для Guzzle\Http\Exception в любом случае нежно объявить алиас, потому что в глобальном пространстве имен существует класс \Exception, не важно, используется он в данном коде или нет.

  3. Форматирование кода

    1. Вызов второго метода в цепочке (включая статические) должен быть перенесен на 2ю строку.
    2. Условие цикла или ифа должно быть записано в одну строку.
    3. Строка не должна превышать 120 символов (за редким исключением, связанным в основном с длинными именами).
    4. Если массив записывается в несколько строчек - после последнего элемента всегда должна стоять запятая.
    5. Допустим только короткий синтаксис массивов (то есть квадратные скобки).
    6. В сигнатуре методов и функций (включая анонимные) необходимо указывать типы. Исключение - отсутствие их поддержки в целевой версии php.
    7. Символ конкатенации стоит отделять пробелами с обеих сторон.
    8. Операторы "return", "yield" и "throw" должны отделяться от основного кода переносом строки. Исключение - они идут следующей строкой после объявления цикла, условного оператора или объявления функции.
    9. Первая строка php-файла содержит только оператор <?php и ничего более (включая комментарии), а так же отделяется дополнительным переносом строки от остального кода.
    10. Каждая логическая операция должна быть отделена от других пустой строкой.
    11. Не допускается разделять код более, чем одной пустой строкой

  4. Оформление doc-блоков и комментариев

    1. Исходные коды не должны содержать информацию об авторе, дате и т.д. Данная информация храниться в системе контроля версий.
    2. Если аргумент или возвращаемое значение может быть разных типов (null тоже считается типом), то их стоит указывать через |, отделяя его пробелами м обеих сторон.
    3. Если метод возвращает void и это указано в сигнатуре функции, то в phpdoc-блоке аннотацию "@return void" можно опустить. Если же версия php не позволяет указать void в сигнатуре функции - то данная аннотация обязательна. Так же её стоит указать в случае, если других аннотация у функции нет.
    4. Каждый блок документации должен выть выравнен по длине его максимального элемента (типа, названия).
    5. Комментарии и описание функций пишутся на русском языке.
    6. Для описания функции (или метода класса) МЫСЛЕННО начинайте предложение со слова "функция", и дальше пишите её назначение. Например, "[Функция] Генерирует новое значение токена".
    7. В конце последнего предложения точка не ставится.
    8. Ключевое слово TODO пишется капсом и с двоеточием после слова TODO. Сам текст пишется как обычно.
    9. Не желательно писать комментарий на той же строке, что и код. Точно не стоит этого делать на одной строке с:
      • управляющими потоком конструкциями (if, else, switch, case, try, catch, do, while, for, foreach, throw, yield, return, etc)
      • с открывающими и закрывающими скобками любых типов (круглые, квадратные, фигурный)
      • Между вызовами методов в одной цепочке
    10. Не стоит писать комментарии между парными конструкциями (например, между if{} и else{} или try{}, catch{} и finally{})
    11. Классам не нужно указывать аннотацию @package.
    12. В phpdoc текстовое описание следует отделять от аннотаций одной пустой строкой.
    13. Phpdoc методов и полей класса должен быть отделен от вышестоящего кода одной пустой строкой. Исключение - phpdoc пишется сразу после объявления класса.
    14. Текстовое описание поля класса в phpdoc должно располагаться выше аннотации @var и отделяться от нее одной пустой строкой.
    15. В функциях и методах класса phpdoc-аннотации должны располагаться в таком порядку: @param, @return, @throws. Все остальные аннотации должны находиться выше @param.
    16. В полях класса последней аннотацией должна быть @var, все остальные должны располагаться выше.
    17. При описании составного типа сначала указывается array, потом ссылочные типы (сначала классы, потом интерфейсы), и далее по убыванию количества возможных значений - string, float, int, bool, null.
    18. Если типом является массив однотипных элементов, то тип этих элементов так же записывается через прямую черту. Например так: "@return array | User[]".
    19. Если типом является коллекция (итерируемый класс) однотипных элементов, то тип этих элементов так же записывается через прямую черту. Например так: "@return UserCollection | User[]".

  5. Объявление переменных

    1. Не следует переопределять уже существующую переменную. Лучше создать новую.
    2. Если какое-то выражение встречается более одного раза (например, обращение к одному и тому же индексу массива или вызов одного и того же метода) - нужно объявить новую переменную. Исключения - Выражение имеет побочные эффекты.
    3. Если какое-то выражение встречается один раз - переменную объявлять не следует. Исключение - объективное улучшение читабельности кода.
    4. Не следует объявлять переменные внутри конструкций if, switch, isset, empty, etc (за исключением циклов for и while), а так же при вызовах функций.