Як іменувати змінні, функції, методи та класи

Щоб упорядкувати код, важливо обрати чіткі правила, за якими ми виводимо імена. Ця сторінка слугує оглядом відносно популярних підходів, що використовуються великою кількістю програмістів, в тому числі мною та людьми, з якими я працюю.

Якщо ви працюєте в команді розробників, неодмінно використовуйте їхні правила, але для загального розвитку так само корисно завести кілька корисних звичок.

Оскільки концепція всього синтаксису PHP дуже широка, я розділив цей посібник на багато вузькоспеціалізованих категорій.

Якщо ви шукаєте швидке рішення, рекомендую вивчити стандарт PSR-4.

Вставка скриптів, посилання на HTML, завантаження файлів

Кожен скрипт повинен починатися з тега <?php.

Якщо в кінці файлу немає без HTML, його не слід завершувати (щоб запобігти появі білого символу в кінці сторінки).

При завантаженні інших файлів слід дотримуватися наступних правил:

• Якщо файл не є критичним і без нього можна обійтися при рендерингу сторінки (наприклад, додаткова інформація в нижньому колонтитулі), його слід завантажувати через include: include 'file.php';.
• Критичні файли тільки через конструкцію require: require 'file.php';.
• Якщо ми працюємо з об'єктами, то використовуємо конструкцію require для завантаження автозавантажувача, який сам подбає про завантаження інших класів (більшість фреймворків реалізують таку поведінку).

Якщо це хоч трохи можливо, то слід відокремити логіку пошуку даних від рендерингу в HTML, тобто використовувати модель MVC (model - view - controller).

Тому ми спочатку готуємо дані в, скажімо, Presenter:

Presenter.php.

$cisla = [1, 2, 3];

$data = [];
$data['цифри'] = $cisla; // передати дані в шаблон
include 'renderCisel.php'; // шаблон завантаження

А потім намалювати його в шаблоні:

renderCisel.php

<table>
<?php
    foreach ($data['cisla'] as $cislo) {
        echo '<tr><td>' . $cislo . '</td></tr>';
    }
?>
</table>

Такий підхід використовується більшістю фреймворків і є корисним для підвищення зрозумілості коду. На більш пізній стадії процесу розробки цей підхід повинен використовувати кожен досвідчений програміст, який хоче розробляти чітко структуровані додатки (для великих додатків цей підхід є обов'язковим).

Імена змінних

Якщо змінна містить масив значень або інші об'єкти, вона повинна бути названа у множині:

$numbers = [1, 2, 3];

Тому що тоді ми можемо просто ітерувати значення на одну цифру:

foreach ($numbers as $number) {
    // обробка чисел
}

Назва, що складається з декількох слів, об'єднується в одне довге слово за синтаксисом comeCase, тобто перше слово починається з малої літери, кожне наступне слово - з великої літери:

$promenna = 'Агов! Агов!';
$seznamUzivatelu = [
   'Ян Барашек',
   'Барак Обама',
   'Стів Джобс',
   'Стівен Вольфрам',
];
$maxFilesInDirectory = 12;
$nameOfPhpScript = 'index.php'; // Скорочено розмір абревіатури PHP

Назви функцій та методів

Функції та методи повинні завжди чітко вказувати в своїй назві, що вони роблять. Часто очікувані вхідні параметри та значення, що повертаються, також можуть бути включені в назву.

Спробуйте здогадатися, що роблять наступні функції і яке значення вони повертають:

getUserById($id);
saveErrorToLog($message);
createDefaultDirectory($path);
setAuthors(['Ян Барашек', 'Чак Норріс']);
getCurrentTime();

Весь фокус в першому слові в назві, яке дає зрозуміти, який метод буде використовувати функція. Зазвичай дотримуються наступної конвенції:

• get - отримати дані у вигляді масиву або об'єкта, вхідні параметри задають шукану сутність
• зберегти - зберегти у файл або базу даних
• створити - створити сутність (наприклад, створити екземпляр об'єкта)
• set - збереження даних у попередньо визначену змінну (всередині функції)

Назви класів

Клас - це велика сутність, яка містить велику кількість властивостей та методів, тому він також повинен починатися з великої літери. Клас також повинен містити тільки одну сутність (і описувати її властивості), тому він повинен мати єдине ім'я. Якщо нам потрібно працювати з декількома сутностями, ми можемо просто зберігати кожен екземпляр в масиві.

Приклад:

class User
{
    public string $username;

    public string $password;

    public string $role;
}

class Users
{
    /** @var User[] */ */ */ */ */ */ */ */ */ */ */ */ */ */
    public array $users;

    public function addUser(User $user): void
    {
        $this->users = array_push($this->users, $user);
    }
}

Клас User спеціалізується на інформації тільки про одного конкретного користувача. Якщо ми хочемо працювати з декількома користувачами, ми створюємо ще один клас (конверт), який несе масив екземплярів конкретної сутності.

Фабрики також часто можуть бути корисними для цього, оскільки вони дозволяють легко створювати подібні об'єкти і переробляти оригінальні екземпляри, що призводить до більш зрозумілого коду при економії системних ресурсів.

Простір імен - Простори імен

Хоча простір імен не залежить від фізичного каталогу, в якому доступний скрипт, гарною практикою є хоча б часткове дотримання структури проекту (що призводить до кращої системи створення нових імен, яка таким чином є більш однозначною).

Особисто я називаю простори імен відповідно до загального підкаталогу для класів цього типу.

Приклади:

App\Presenters; // Це імена всіх доповідачів
App\Model;      // Це назва загальної моделі
App\Model\Math; // Так називається модель, яка працює з математикою

Для правильного автозавантаження класів варто дотримуватися стандарту PSR-4.

Ненормативні звичаї (наприклад, в корпоративному колективі)

А як ви називаєте свою? Буду вдячний за поради, як покращити цю статтю.

Загалом, однак, користувацькі домовленості в команді не мають особливого сенсу, оскільки це ускладнює перенесення коду на інші фреймворки, і вам доведеться вивчати поточні домовленості, коли ви наймаєте на роботу нового колегу. Тому найкраще дотримуватися стандарту PSR-4.

Jan Barášek   Více o autorovi

Autor článku pracuje jako seniorní vývojář a software architekt v Praze. Navrhuje a spravuje velké webové aplikace, které znáte a používáte. Od roku 2009 nabral bohaté zkušenosti, které tímto webem předává dál.

Rád vám pomůžu:

Kontakt