Стандарты написания кода в компании VIS-A-VIS

Стандарты написания кода в компании VIS-A-VIS

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

Ниже рассмотрено 18 основных правил:

Правило 0. PSR - 1/2

Это правило под цифрой 0, потому что этот пункт основа всего.

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

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

 

Правило 1. Single Responsibility Principle (принцип единой ответственности)

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

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

 

Правило 2. Dry принцип (не повторяй себя)

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

 

Правило 3. Не использовать else

Звучит довольно странно? Как это писать код без else?

А вы попробуйте и сразу увидите, как код стал лучше и понятнее.

Практически любой код можно написать без использования оператора else. Если все-таки нужно писать else, то используйте тернарные операторы

 

Правило 4. Не сорить там, где уже кто-то насорил до вас

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

Попытайтесь отрефакторить существующий код и дальше писать код по всем стандартам.

 

Правило 5. Не писать велосипеды

Мы используем в своих проектах популярный фреймворк Laravel и 70% кода, который нужен, уже написан и оттестирован кем-то до нас. Нужно просто его использовать.

Делая ревью Laravel проекта часто можно встретить следы нативного php кода, которые увеличивает исходный код в разы.

Обычно такой код возникает от недостаточного знания фреймворка. Такой код нужно не допускать в production.

 

Правило 6. Вложеность операторов if и foreach не должна быть больше двух

Глубокие вложенности усложняют понимание кода.

 

Правило 7. Параметры в функциях (методах)

​7.1 Количество параметров

Должно быть не больше, чем 2 параметра.

Чем меньше параметров в функции (методе), тем лучше, а в идеале вообще без параметров.

7.2 Избегайте булевые флаги в аргументах

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

Они сильно запутывают код.

Правило 8. Наименования

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

Название модели должно быть, как название таблицы в единственом числе, если таблица называется users, то модель должна называться User.

Методы, которые обрабатывают запрос, например, обработчики форм. Такие методы должны начинаться с префикса do.

Пример имен методов обработчиков: doUpdateAdForm, doRemoveAd, doChangeStatus.

Методы, которые делают логические проверки. Возвращаемый результат их вызова в большинстве случаев булевский true / false.

Такие методы должны иметь префикс is или has, например: hasUserEmail, isProductExists.

Гетеры и сетеры.

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

Пример: getContent, setUserEmail, getSystemErrors.

 

Правило 9. Комментарии

Не пишите комментарии, особенно если они такие:

// this is a dog
$dog = new Dog ();

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

 

Правило 10. Закомментированный код

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

Не забывайте удалять его.

 

Правило 11. БД

Название полей и таблиц должны быть такик, как рекомендует Laravel, таблицы в множественном числе (products, users и так далее), связующие колонки между таблицами название таблице в единственом числе нижнее подчеркивание id (user_id, product_id и т.д.).

Колонки с булевыми значениями должны иметь префикс is_ либо has_ например has_active или is_active

 

Правило 12. "Волшебные числа"

Заменяйте "волшебные числа" именованными константами.

 

Правило 13. Массивы

Ключи ассоциативных массивов пишутся в snake_case и никаких camelCase (исключение, если юзается compact() ).

Ключи для обычного массива не присваиваются вручную.

Недопустимо:

$array = [];
$array[42] = 'wtf';

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

Плохо:

$newArray = ['some_default' => 'values', 'another_default' => 'more values'];

Хорошо:

$newArray = [
'some_default' => 'values',
'another_default' => 'more values',
];

 

Правило 14. Строки

Все строки нужно размещать только в одинарных кавычках

Плохо:

$str = “Hello world - $age”;

Хорошо:

$str = ‘Hello world - ’ . $age;

 

Правило 15. Короткий и читаемый синтаксис там, где это возможно

Session::get('cart') --- session('cart')
$request->session()->get('cart') --- session('cart')
return Redirect::back() --- return back()
return view('index')->with('title', $title)->with('client', $client)
--- return view('index', compact('title', 'client'))

 

Правило 16. Индексы циклов

Это нормально, когда небольшой цикл из 1-3 строк имеет индекс под названием i, j или k.

Но если тело цикла заметно больше, то лучше давать индексам осмысленные имена. И вам будет проще разобраться с таким кодом со временем.

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

Плохо:

foreach($array as $k=>$v) {}

Хорошо:

foreach($array as $slug => $product)

 

Правило 17. Читабельные условия в if операторе

Если в if больше чем 2 условия, то лучше вынести все условия в отдельную переменную или метод.

Плохо:

if ($user->sex = ‘m’ && ($user->age > 18 || $user->age < 65)) {

}

Хорошо:

if ($user->ifAccess()) {

}
Class User {
private function ifAccess () {
return $this->sex = ‘m’ && ($this->age > 18 || ($this->age < 65))
}
}

 

Правило 18. Организация методов в моделях

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

Сначала идут мутаторы, потом скоупы, потом связи, публичные методы, протектод и в конце приватные, пример такого класса ниже:

class MySuperModel()
{
public function getAttributesTest();
public function scopeTest();
public function relavionsTest();
public function ();
protected function()
private function();
}

Популярные статьи в разделе Разработка сайтов
Разработка сайтов
Тренды веб-дизайна 2017: 11 способов быть на шаг впереди MakeBeCool
Вот и 2016 год уже подходит к концу. Многие начинают его анализировать и формировать выводы. Диза...
Разработка сайтов
Какая конверсия landing page считается хорошей? Impulse Design
Показатель конверсии Landing page – это непосредственная оценка эффективности одностраничка и, ка...
Разработка сайтов
Что выбрать — шаблон или уникальный дизайн? Promodex
В процессе создания продающего сайта неизбежно станет вопрос о внешнем виде, дизайнерском оформлении...