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

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 = новий 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 – Артур Щаблевський.

Сподобалася стаття ? - Поділіться посиланням ::