Monstra - Стандарты оформления кода

Стандарты оформления кода

Этим стандартам оформления кода и документации должны в обязательном порядке следовать все разработчики Monstra. Любой код, который не соответствует этим требованиям, приниматься не будут.

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

PHP теги

Всегда используйте длинный тег открытыя. Никогда не используйте короткие теги или стиль ASP. Файлы, содержащих только PHP код должен всегда опускать закрытия тега PHP (>). Это предотвращает многие неуловимые ошибки, ведущие к белым экранам смерти.

Отступы

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

Завершение строк

Символы окончаний строки должны быть Unix-стиле LF.

Именование файлов

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

Кодировка

Файлы должны быть сохранены в UTF-8 кодировке и без BOM.

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

Классы

Имена класов должно быть в "верблюдном" CamelCase стиле, и каждое слова в названии класса должно быть с Заглавной буквы.

class Blog {
}

Функции/Методы

Имена функции/методов должны быть написаны в "нижнем верблюжьем" lowerCamelCase стиле, и каждок слово в названии функции/метода с Заглавной буквы, кроме первого слова.

class Blog {
    function getPost() {
        // Some code here...
    }
}

Переменные

Имена переменных должны быть краткими и содержать только строчные буквы. При использовании имен, состоящих из нескольких слов, все слова пишутся со строчной (маленькой) буквы и разделены между собой знаком “_” (нижнее подчеркивание). Итераторы циклов должны быть короткими, предпочтительно один символ.

$user_login = 'Awilum';

Константы

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

THEMES
PLUGINS
PLUGINS_BOX

Ключевые слова

Ключевые слова, такие как true, false, null, as и т.д. должны быть в нижнем регистре, а слова в верхнем регистре зарезервированы для констант. То же самое касается примитивных типов, таких как array, integer, string.

Управляющие конструкции

Управляющие конструкции, такие ключевые слова как if, for, foreach, while, switch должны быть отделены пробелами от параметров/аргументов и расположены по одному на строке . Фигурные скобки должны распологаться на отдельных и разных строчках (тип BSD).

for ($j = 1; $j < 5; $j++) {
    for ($j = 1; $j < 5; $j++) { 
        doSomething(); 
    }
} 
if ((condition1) || (condition2)) {
    // Action 1
} elseif ((condition3) && (condition4)) {
    // Action 2
} else {
    // Default action
} 
// Space before and after '!'
if ( ! condition) {
    // Do something...
}

Другая запись конструкции if

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

Не используйте это, когда оба if и else необходимо, просто в таких случаях один условный оператор.

// instead of if (isset($var)) { Option::add('var', $var); }
isset($var) and Option::add('var', $var);
// instead of if ( ! isset($var)) { $var = Option::get('var'); }
isset($var) or $var = Option::get('var');
// Or this:
$var = Uri::segment(3) ? Uri::segment(3) : 'default';
// Or actually this:
$var = Uri::segment(3) ?: 'default';

Сравнение, логические операторы

Сравнение возвращаемых значений функций/методов и переменные должны быть только если тип результа известен, например, некоторые функции могут вернуться ложным, и при сравнении этого результата функций можно использвоать логические операторы, такие как === и! ==. Кроме того, использование and или or предпочтительнее, чем && или || для удобства чтения. В некоторых случаях, это не может быть заменено и использование && или || в качестве необходимых операторов может быть использованыо.! должно быть пробелов с обеих сторон при использовании.

if ($var == false and $other_var != 'some_value')
if ($var === false or my_function() !== false)
if ( ! $var)

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

/**
 * Returns a greeting.
 * 
 * @access  public
 * @param   string  $name  Name of the person you want to greet
 * @return  string
 */ 
public static function greeting($name){
    return 'Hello, ' . $name . '!';
}

Documentation