Як розібратися в PHP коді

Більшість мов можна писати по-різному, з однаковим результатом. У той же час, написавши код, ви, ймовірно, колись у майбутньому прочитаєте його і виправите або додасте нові функції.

Тому, щоб не думати весь час про код і добре в ньому орієнтуватися, існує набір інструментів і способів "правильного написання коду" безпосередньо в PHP, або побудови коду таким чином, щоб безпосередньо підтримувати його майбутню читабельність (навіть іншою людиною).

Примітка автора:.

Досвід показує, що код застаріває настільки швидко, що навіть сам автор програми вже через півроку сприймає власний код як чужий. Тож якщо ми правильно напишемо його з самого початку, то це не завадить його подальшій розширюваності.

В реальній розробці негласно показано, що єдине форматування коду і введення правил в цілому запобігає ряду помилок.

TL;DR

Читабельність коду часто пов'язана з правилами форматування та запису.

У командах розробників має сенс встановити формальні правила для форматування та підтримки коду.

Особисто я використовую (в 2022 році) стандарт кодування для фреймворку Nette і правила оцінюються автоматично в кожному комміті. Більш детальну інформацію див. у статті про [використання GitHub CI] (https://php.baraja.cz/github-actions-nejlepsi-ci-pro…).

Встановлення тесту стандарту кодування та його запуск здійснюється за допомогою пари команд:

composer create-project nette/coding-standard temp/coding-standard ^3 --no-progress --ignore-platform-reqs
php temp/coding-standard/ecs check src

Примітки до коду

Примітки не впливають на роботу коду і призначені тільки для використання програмістом. Для великих, більш повних фрагментів коду важливо написати примітку, яка пояснює, для чого призначений код і як він працює в принципі.

// Визначення змінних
$a = 5;
$b = 3;
$c = 2;

// Сума всіх чисел
$sum = $a + $b + $c;

// Лістинг для користувачів
echo $sum;

Примітка починається з пари косих рисок (//) і діє до кінця рядка. Його можна використовувати будь-де.

У записці не слід пояснювати конкретну реалізацію алгоритму, а лише його загальні принципи. Це пов'язано з тим, що з часом код може кілька разів змінюватися, і в такому випадку ми також повинні внести відповідні зміни до примітки.

Примітка автора:.

Часто буває так, що код не робить саме те, що пояснюється в його описі. В основному це пов'язано з тим, що програміст десь помилився. Тому в примітці слід описати загальні принципи, щоб ми могли потім внести відповідні зміни до кодексу. Але ніколи не забувайте, що єдину правду про те, що насправді відбувається в додатку, описує тільки фактичний код, і примітка на це ніяк не впливає.

Графічне розділення частин коду

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

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

/**
 * Функція обчислює середнє арифметичне.
 *
 * 1. отримання списку номерів
 * 2. Отримання суми та кількості чисел
 * 3. обчислити та вивести середнє арифметичне
 */

// 1.
$numbers = [1, 3, 8, 12];

// 2.
$sum = array_sum($numbers);
$count = count($numbers);

// 3.
echo 'В середньому - так:' . ($sum / $count);

Символи /** починають багаторядковий коментар, який діє до маркера */. Для того, щоб його було легко читати, доцільно ставити зірочку на початку кожного рядка.

Коментарі до документації

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

У більш ранніх версіях PHP (до 7.0) типи даних ще не використовувалися, тому тип тієї чи іншої змінної описувався безпосередньо в коментарі.

/**
 * @автор Ян Барашек <jan@barasek.com>
 * @ліцензія Массачусетського технологічного інституту
 * @link https://php.baraja.cz
 * @param float[] $numbers
 */
function average(array $numbers): float
{
    $sum = array_sum($numbers);
    $count = count($numbers);

    return $sum / $count;
}

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

Писати код чеською чи англійською мовою?

Я пишу весь код тільки англійською мовою (включаючи назви функцій, змінні, коментарі, ...).

Це має низку переваг:

• Розробник може проактивно тренувати свою англійську відразу.
• Значна частина програми використовує сторонні бібліотеки, які є англомовними, тому вона автоматично підтримує узгодженість
• Більшість просунутих речей взагалі не мають англійського перекладу
• Впевнений, ви можете навести багато інших прикладів

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

Повністю локалізований код англійською мовою також використовується в компаніях, тому корисно практикувати англійську мову з самого початку.

Порядок виконання числових операцій

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

Хорошим рішенням видається спочатку збільшити числа, а потім обчислювати з найбільшими можливими числами. Таким чином, статистично менше викривлень.

Приклад:

echo 10 / 3; // Він пише 3.33333333333333333

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

echo 1 / 2 * 2; // це гірше, тому що 1/2 = 0.5*2 = 1
echo 2 * 1 / 2; // так краще, тому що 2*1 = 2/2 = 1

Коли ви вирішуєте великі, складні числові операції, використовуйте дроби для запису чисел.

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