Стандарты написания кода

8 Января 2019

В каждой уважающей себя IT-компании существуют стандарты написания кода.

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

В "VIS-A-VIS" за 15 лет практики, набитых шишек, методом проб и ошибок, мы выработали свои правила с которыми хотим поделиться в этой статье.

Для чего нужны стандарты написания кода?

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

Когда код в едином стиле в нем намного проще разобраться, не правда ли?

Код должен быть написан, как будто его писал один человек, а не так что просматривая код проекта можно было сказать что эти строчки писала Маша, она любила использовать snake_case вместо camelCase. А этот код Вася у него контроллеры раздувались на сотни строк кода.

Часто обслуживание такого рода кода будет стоит в несколько раз дороже чем изначальная его разработка.

Так давайте же думать о наших коллегах-программистах которые через месяц, год или два года заглянут в ваш код и скажут: 

– “Вах! Какой чудесный код, многих лет добра и здоровья автору этого кода и его детям”, а не “Какой мудак мог написать такой говнокод?!”.

 

Итак, правила написания кода:

0. PSR - 1/2

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

"Это как ходить писать в туалет в унитаз, а не там где приспичит".

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

Статью, как писать чистый и красивый код в PhpStorm я уже писал ранее (см. по ссылке ниже):

https://www.vis-design.com/ru/blog/kak-pisat-chistyi-i-krasivyi-kod-v-phpstorm-pri-pomoshi-plaginov-sonarlint-i-code-sniffer.htm

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Такой код нужно не допускать в продакшн.

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

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

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();
}

 

Статью подготовил PHP-разработчик диджитал агентства VIS-A-VIS – Артур Щаблевский.

Понравилась статья? – Поделитесь ссылкой::