docs/internals-ru/core-code-style.md
Описанный ниже стиль кодирования используется при разработке ядра Yii 2.x и его официальных расширений. Если вы хотите участвовать в разработке фреймворка, постарайтесь придерживаться данного стиля. Мы не принуждаем вас использовать этот стиль при разработке ваших приложений с использованием Yii 2. В данном случае можете использовать тот стиль, который вам больше подходит.
Пример конфигурационного файла для CodeSniffer вы можете найти здесь: https://github.com/yiisoft/yii2-coding-standards
В общем, мы используем совместимый со стандартом PSR-2 стиль, так что все положения PSR-2 вполне применимы к нашему стилю кодирования.
<?php или <?=;StudlyCaps;camelCase;camelCase;private;elseif вместо else if.<?php ?> или <?=; НЕ ДОЛЖНЫ использоваться другие теги, такие как <?;?> не нужен;.php.PHP код должен содержать только символы в кодировке UTF-8 без BOM.
Имена классов ДОЛЖНЫ быть определены используя StudlyCaps. Например, Controller, Model.
В данном случае, под классом подразумеваются все классы и интерфейсы.
CamelCase;/**
* Документация
*/
class MyClass extends \yii\base\BaseObject implements MyInterface
{
// код
}
Константы класса ДОЛЖНЫ быть объявлены в верхнем регистре с подчеркиванием в качестве разделителей. Пример:
<?php
class Foo
{
const VERSION = '1.0';
const DATE_APPROVED = '2012-06-01';
}
public;$_varName;$camelCase
с первой буквой в нижнем регистре;$i и $j лучше не использовать.Пример:
<?php
class Foo
{
public $publicProp1;
public $publicProp2;
protected $protectedProp;
private $_privateProp;
public function someMethod()
{
// ...
}
}
camelCase с первой буквой в нижнем регистре;private, protected или
public. Использование var недопустимо;/**
* Документация
*/
class Foo
{
/**
* Документация
*/
public function bar()
{
// код
return $value;
}
}
@param, @var, @property и @return должны описывать типы bool, int, string, array или null. Вы можете использовать и имена классов, например Model или ActiveRecord. Для типизированных массивов используйте ClassName[].
__construct вместо старого стиля, применяемого в PHP 4.true, false, null и array.Изменение типа существующей переменной считается плохой практикой. Постарайтесь не использовать такой подход, за исключением случаев, когда это действительно необходимо.
public function save(Transaction $transaction, $argument2 = 100)
{
$transaction = new Connection; // плохо
$argument2 = 200; // хорошо
}
$str = 'Например так.';
$str1 = "Привет, $username!";
$str2 = "Привет, {$username}!";
Следующий вариант запрещен:
$str3 = "Привет, ${username}!";
При конкатенации строк выделяйте точку пробелами:
$name = 'Yii' . ' Framework';
Для длинных строк используйте следующий подход:
$sql = "SELECT *"
. "FROM `post` "
. "WHERE `id` = 121 ";
Для массивов мы используем краткий синтаксис, появившийся в PHP 5.4.
Используйте следующий стиль:
$arr = [3, 14, 15, 'Yii', 'Framework'];
При большом количестве элементов:
$arr = [
3, 14, 15,
92, 6, $test,
'Yii', 'Framework',
];
Для ассоциативных массивов используйте следующий стиль:
$config = [
'name' => 'Yii',
'options' => ['usePHP' => true],
];
if ($event === null) {
return new Event();
}
if ($event instanceof CoolEvent) {
return $event->instance();
}
return null;
// такой код недопустим:
if (!$model && null === $event)
throw new Exception('test');
Старайтесь избегать использования else после return там, где это возможно.
Используйте граничные операторы.
$result = $this->getResult();
if (empty($result)) {
return true;
} else {
// дальнейшие вычисления
}
лучше переписать так:
$result = $this->getResult();
if (empty($result)) {
return true;
}
// дальнейшие вычисления
Используйте следующий стиль для switch:
switch ($this->phpType) {
case 'string':
$a = (string) $value;
break;
case 'integer':
case 'int':
$a = (int) $value;
break;
case 'boolean':
$a = (bool) $value;
break;
default:
$a = null;
}
doIt(2, 3);
doIt(['a' => 'b']);
doIt('a', [
'a' => 'b',
'c' => 'd',
]);
Не забывайте про пробелы между ключевыми словами function/use и открывающими круглыми скобками:
// правильно
$n = 100;
$sum = array_reduce($numbers, function ($r, $x) use ($n) {
$this->doMagic();
$r += $x * $n;
return $r;
});
// неправильно
$n = 100;
$mul = array_reduce($numbers, function($r, $x) use($n) {
$this->doMagic();
$r *= $x * $n;
return $r;
});
@return если метод не возвращает значение;yii\base\BaseObject, документируются тегом @property в блоке документации класса;
Аннотации геттеров и сеттеров автоматически генерируются из соответствующих тегов @return or @param
посредством выполнения команды ./build php-doc в соответствующем каталоге;
Вы можете добавить дополнительный тег @property для геттера или сеттера для пояснения назначения переменной метода, если это необходимо.
Например:<?php
/**
* Returns the errors for all attribute or a single attribute.
* @param string $attribute attribute name. Use `null` to retrieve errors for all attributes.
* @property array An array of errors for all attributes. Empty array is returned if no error.
* The result is a two-dimensional array. See [[getErrors()]] for detailed description.
* @return array errors for all attributes or the specified attribute. Empty array is returned if no error.
* Note that when returning errors for all attributes, the result is a two-dimensional array, like the following:
* ...
*/
public function getErrors($attribute = null)
<?php
/**
* @link https://www.yiiframework.com/
* @copyright Copyright (c) 2008 Yii Software LLC
* @license https://www.yiiframework.com/license/
*/
/**
* Component is the base class that provides the *property*, *event* and *behavior* features.
*
* @include @yii/docs/base-Component.md
*
* @author Qiang Xue <qiang.xue@gmail.com>
* @since 2.0
*/
class Component extends \yii\base\BaseObject
/**
* Returns the list of attached event handlers for an event.
* You may manipulate the returned [[Vector]] object by adding or removing handlers.
* For example,
*
* ```
* $component->getEventHandlers($eventName)->insertAt(0, $eventHandler);
* ```
*
* @param string $name the event name
* @return Vector list of attached event handlers for the event
* @throws Exception if the event is not defined
*/
public function getEventHandlers($name)
{
if (!isset($this->_e[$name])) {
$this->_e[$name] = new Vector;
}
$this->ensureBehaviors();
return $this->_e[$name];
}
Как вы можете видеть в примерах выше, мы используем специальную разметку для форматирования комментариев PHPDoc.
Ниже описан дополнительный синтаксис для описания связей между классами, методами и свойствами в документации:
[[canSetProperty]] создаст ссылку на метод или свойство canSetProperty этого класса;[[Component::canSetProperty]] создаст ссылку на метод canSetProperty класса Component того же пространства имен;[[yii\base\Component::canSetProperty]] создаст ссылку на метод canSetProperty класса Component в пространстве имен yii\base;[[Component]] создаст ссылку на класс Component в том же пространстве имен. Здесь так же возможно явное указание пространства имен.Для явного указания текста ссылки возможно использование следующего синтаксиса:
... as displayed in the [[header|header cell]].
Часть до | это имя свойства, метода или класса для ссылки, а часто поле | это текст ссылки.
Так же, возможно создание ссылок на Руководство:
[Руководство](guide:file-name.md)
[Раздел руководства](guide:file-name.md#subsection)
В примерах кода должен использоваться синтаксис Markdown, но не должен указываться язык. Указание языка в примерах кода может привести к нарушению их отображения в некоторых IDE. Пример:
/**
* Correct code example:
*
* ```
* $object->doMagic();
* ```
*/
public function doMagic()
{
}
/**
* Incorrect code example:
*
* ```php
* $object->doMagic();
* ```
*/
public function doMagic()
{
}
//, а не с #;=== [] или empty()Используйте empty(), где это возможно.
Не допускайте запутанных вложенных условных конструкций, используйте return. Для коротких методов это не актуально.
self или staticВсегда используйте static, за исключением следующих случаев:
self: self::MY_CONSTANT;self: self::$_events;self для рекурсивного обращения к текущему классу, вместо класса наследника.Свойства указывающее компоненту на отсутствие необходимости что-либо делать, должны принимать значение false. Null, '', или [] не должны использоваться в таких случаях.