16 кращих практик для написання читаного коду: що треба знати будь-якому програмістові перед улаштуванням на роботу і не лише


Дізнайтесь більше про нові кар'єрні можливості в EchoUA. Цікаві проекти, ринкова оплата, гарний колектив. Надсилайте резюме та приєднуйтеся до нас.

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

 

Публікуємо переклад, зроблений для Tproger міжнародною IT-компанією Noveo.

1. Коментування і документація

За останні 5 років середовища розробки (IDE) пройшли великий шлях. Це зробило коментування коду важливим як ніколи. Використання певних стандартів коментування дозволяє середовищу розробки та іншим інструментам використати коментарі певним чином.

Розглянемо цей приклад:

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

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

2. Послідовні відступи

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

Є декілька варіантів виставляння відступів:

Стиль 1:

function foo (){ if ($maybe) { do_it_now (); again (); } else { abort_mission (); } finalize ();}

Стиль 2

function foo (){ if ($maybe) {
do_it_now (); again (); } else { abort_mission (); } finalize ();}

Стиль 3

function foo (){ if ($maybe) { do_it_now (); again (); } else { abort_mission (); } finalize ();}

Раніше я використав другий стиль, але нещодавно перейшов на перший. Втім, це справа смаку. Немає “кращого” стилю, якого повинні дотримуватися всі без винятку. Насправді кращий стиль – це послідовний стиль. Якщо Ви берете участь у проекті в складі команди, необхідно дотримуватися стилю, який вже використовується на проекті.

Стилі відступів не завжди можна відрізнити один від одного: іноді змішуються різні правила. Наприклад, в PEAR Coding Standards відкриваюча дужка (“{“) залишається на тому ж рядку, що і контролюючі структури, але переноситься на наступний рядок при визначенні функцій.

Стиль PEAR:

function foo (){ // placed on the next line if ($maybe) { // placed on the same line do_it_now (); again (); } else { abort_mission (); } finalize ();}

Також можна зазначити, що замість табуляції для відступів використовується чотири пропуски.

Тут знаходиться стаття Вікіпедії, де можна прочитати про різні стилі відступів. А тут Ви можете знайти відмінний інструмент, який дозволяє створити єдиний формат налаштувань, що назавжди вирішить питання типу “таби або пропуски” для всіх IDE і всіх мов програмування.

3. Уникайте очевидних коментарів

Коментувати код – це чудово, але іноді коментарі стають необов’язковими або просто зайвими.

Візьмемо цей приклад:

// get the country code$country_code = get_country_code ($_ SERVER['REMOTE_ADDR']); // if country code is US
if ($country_code == 'US') { // display the form input for state echo form_input_state ();}

Коли текст настільки очевидний, немає сенсу дублювати його коментарем.

Якщо ж коментар потрібний, можна зробити це одним рядком:

// display state selection for US users$country_code = get_country_code ($_ SERVER['REMOTE_ADDR']);if ($country_code == 'US') { echo form_input_state ();}

4. Групування коду

Як правило, для виконання певних задач потрібно декілька рядків коду. Розумно оформляти такі задачі окремими блоками з розривами між ними.

Наведемо приклад:

// get list of forums$forums = array ();$r = mysql_query ("SELECT id, name, description FROM forums");while ($d = mysql_fetch_assoc ($r)) {
$forums []= $d;} // load the templatesload_template ('header');load_template ('forum_list',$forums);load_template ('footer');

Послідовність у найменуваннях

PHP сам не завжди буває послідовним у найменуваннях:

  1. strpos () при str_split ()
  2. imagetypes () при image_type_to_extension ()

Передусім в іменах має бути помітною межа слів. Є два популярні варіанти:

  1. camelCase: заголовною стає перша буква кожного слова, крім першого.
  2. Нижнє_Підкреслювання: слова розділяються нижнім підкресленням, наприклад, mysql_real_escape_string ().

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

Наприклад, велика частина проектів на Java використовує camelCase, тоді як в PHP популярніше нижнє підкреслення.

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

Повторюся: немає “кращого” стилю. Просто будьте послідовними.

5. Принцип DRY

DRY – абревіатура від англійського Don’t Repeat Yourself (не повторюйтеся). Іноді використовується варіант DIE – Duplication Is Evil (повторення – це зло).

Принцип свідчить: “Кожен елемент знання повинен мати в системі єдине, таке, що не викликає сумнівів і авторитетне значення”.

Мета більшості додатків (чи комп’ютерів у цілому) – автоматизувати повторювану задачу. Цього принципу треба дотримуватися у будь-якому коді, навіть коли йдеться про веб-додаток. Один фрагмент не повинен повторюватися в коді знову і знову.

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

От як створюються шаблони в CodeIgniter:

$this ->load ->view ('includes/header');$this ->load ->view ($main_content);$this ->load ->view ('includes/footer')

6. Уникайте глибокої вкладеності коду

Надто велика кількість рівнів вкладення утруднює читання і розуміння коду.

function do_stuff (){ // ... if (is_writable ($folder)) { if ($fp = fopen ($file_path,'w')) { if ($stuff = get_some_stuff()) { if (fwrite ($fp,$stuff)) { // ... } else { return false; } } else { return false; } } else { return false; } } else { return false; }}

Заради зручності читання можна змінити код, щоб зменшити кількість рівнів вкладення:

function do_stuff (){ // ... if (!is_writable ($folder)) { return false; } if (!$fp = fopen ($file_path,'w')) { return false; } if (!$stuff = get_some_stuff()) { return false; }
if (fwrite ($fp,$stuff)) { // ... } else { return false; }}

7. Обмежте довжину рядка

Нашим очам зручніше читати довгі й вузькі колонки тексту. Саме тому статті в газетах зазвичай виглядають так:

Уникати довгих рядків коду – корисна практика.

// bad$my_email ->set_from('test@email.com') ->add_to('programming@gmail.com') ->set_subject ('Methods Chained') ->set_body ('Some long message') ->send (); // good$my_email ->set_from('test@email.com') ->add_to('programming@gmail.com') ->set_subject ('Methods Chained') ->set_body ('Some long message') ->send (); // bad
$query = "SELECT id, username, first_name, last_name, status FROM users LEFT JOIN user_posts USING (users.id, user_posts.user_id) WHERE post_id = '123'"; // good$query = "SELECT id, username, first_name, last_name, status FROM users LEFT JOIN user_posts USING (users.id, user_posts.user_id) WHERE post_id = '123'";

Крім того, якщо комусь потрібно буде читати код з вікна термінала (як, наприклад, користувачам Vim), то буде розумно обмежити довжину рядка 80 символами.

8. Організація файлів і тек

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

На своїх перших проектах я знав про ідею створення “включених файлів”, але я тоді був не дуже організованою людиною. Я створив теку “inc” з двома файлами: db.php і functions.php. Але додатки збільшувались, файл із функціями став величезним, і підтримувати його виявилось неможливим.

Щоб уникнути цього можна або використати фреймворк, або імітувати файлову структуру. Ось так, наприклад, виглядає CodeIgniter:

10. Послідовність у тимчасових іменах

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

Треба підтримувати послідовність імен для тимчасових змінних, у яких є певна роль. Ось декілька прикладів, які я використовую в коді:

// $i for loop countersfor ($i = 0; $i < 100; $i++) { // $j for the nested loop counters for ($j = 0; $j < 100; $j++) { }} // $ret for return variablesfunction foo (){ $ret['bar'] = get_bar (); $ret['stuff'] = get_stuff (); return $ret;} // $k and $v in foreachforeach ($some_array as $k => $v) { } // $q, $r and $d for mysql$q = "SELECT * FROM table";$r = mysql_query ($q);while ($d = mysql_fetch_assocr ($r)) { } // $fp for file pointers$fp = fopen ('file.txt','w');

11. Пишіть спеціальні слова SQL заголовними буквами

Взаємодія з базою даних – істотна частина більшості веб-додатків. Якщо Ви пишете SQL-запити, то буде розумно зробити їх читаними.

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

SELECT id, username FROM user; UPDATE user SET last_login = NOW () WHERE id = '123' SELECT id, username FROM user uLEFT JOIN user_address ua ON (u.id = ua.user_id) WHERE ua.state = 'NY'GROUP BY u.idORDER BY u.usernameLIMIT 0,20

12. Розділення коду і даних

Це ще один принцип, який стосується практично всіх мов програмування в усіх середовищах розробки. У разі веб-розробки “дані” зазвичай означають виведення HTML.

Багато років тому, під час першого релізу PHP, це було реалізовано як движок шаблонів. Тоді HTML-файли з декількома рядками на PHP були звичною справою. У будь-якому випадку, з часом ситуація сильно змінилася і сайти стали динамічнішими та функціональними. Зараз код становить значну частину веб-додатків, і сполучати його з HTML буде недоцільним.

Ви можете або самостійно застосувати цей принцип до свого додатка, або використати сторонні інструменти (шаблонізатори, фреймворки, CMS) і наслідувати їх домовленості.

Популярні PHP-фреймворки:

  1. CodeIgniter
  2. Zend Framework
  3. Cake PHP
  4. Symfony

Популярні шаблонізатори:

  1. Smarty
  2. Dwoo
  3. Savant

13. Змінюйте синтаксис усередині шаблонів

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

Наведу приклад:

Hello,
|

My Message Board

 

 

( threads)

 

 

Це дозволяє уникнути багатьох фігурних дужок. Крім того, за відступами і структурою код стає схожим на HTML-розмітку.

14. Об’єктно-орієнтоване проти процедурного

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

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

class User { public $username; public $first_name; public $last_name; public $email; public function __construct (){ // ... } public function create (){ // ... } public function save (){ // ... } public function delete (){ // ... } }

Процедури і функції можна використати для задач, які можуть виконуватися окремо.

function capitalize ($string) { $ret = strtoupper ($string[0]); $ret .= strtolower (substr ($string, 1)); return $ret; }

15. Читайте Open Source код

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

16. Рефакторинг

Коли Ви проводите рефакторинг, то міняєте код, не змінюючи можливості системи. Це можна представити як “чищення” коду для підвищення читаності та якості.

Рефакторинг не відноситься до багфіксингу або додавання функціонала. Можна рефакторити код, який був написаний учора, поки він ще свіжий у Вашій голові, щоб він був більше читаним і доступним для перевикористання, коли Ви повернетеся до нього через два місяці. Як свідчить стара істина “рефакторьте раніше, рефакторьте частіше”.

Ви можете використати будь-які з перерахованих “кращих практик” у процесі рефакторингу.

Переклад підготовлений міжнародною IT-компанією Noveo.

Top 15+ Best Practices for Writing Super Readable Code

Київ, Харків, Одеса, Дніпро, Запоріжжя, Кривий Ріг, Вінниця, Херсон, Черкаси, Житомир, Хмельницький, Чернівці, Рівне, Івано-Франківськ, Кременчук, Тернопіль, Луцьк, Ужгород, Кам'янець-Подільський, Стрий - за статистикою саме з цих міст програмісти найбільше переїжджають працювати до Львова. А Ви розглядаєте relocate?


Залишити відповідь

Ваша e-mail адреса не оприлюднюватиметься. Обов’язкові поля позначені *