Лучшие 15+ практик написания читабельного кода

() translation by (you can also view the original English article)

Два раза в месяц, мы пересматриваем статьи, которые нравятся больше всего нашим пользователям на сайте Nettuts+.

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

1 - Комментарии и документация

IDE (Integrated Development Environment, среда разработки) прошли долгий путь за последние пять лет. Тем самым комментирование кода, стало важным аспектом, как никогда раньше. Следование определённым стандартам комментариев, позволяет IDE и другим инструментам обрабатывать их различными методами.

Взгляните на пример:

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

Вот другой пример, где я вызываю функцию из сторонней библиотеки:

В данном примере, такой тип комментариев (или документации) основан на PHPDoc, и показан в IDE Aptana.

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

Я использовал стиль кода под номером 2, но недавно перешёл на номер 1. Но дело тут исключительно в предпочтениях каждого. Нет "лучшего" стиля, которому все должны следовать. На самом деле, лучший стиль, тот стиль при котором отступы остаются одинаковыми и стиль является последовательным. Если вы член какой-либо команды разработчиков или добавляете код в проект, вы должны следовать существующему стилю, который используется.

Стили индентации не всегда сильно отличаются друг от друга. Иногда они совмещают несколько различных правил. К примеру, в стандарте кода PEAR, открывающая угловая скобка "{" идёт на той же строке где расположена управляющая конструкция, но переносится на другую строку в определении функции.

Стиль PEAR:


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

Также обратите внимание на четыре пробела вместо табов для индентации.

Вот статья на Wikipedia с примерами различных стилей отступов.

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 templates
load_template('header');
load_template('forum_list',$forums);
load_template('footer');

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

5 - Последовательное именование

PHP сам по себе иногда не следует последовательной договорённости об именах:

strpos() и str_split()
imagetypes() и image_type_to_extension()

Для начала, имена должны содержать ограничения слов. Есть две популярных опции:

Верблюжья нотация (camelCase): первая буква каждого слова - заглавная, за исключением первого слова.
Нижнее подчёркивание: нижнее подчеркивание между словами, к примеру: mysql_real_escape_string().

Обладая несколькими опциями возникает ситуация на подобии стилей индентации, которую я упоминал ранее. Если существующий проект следует определённой договорённости, вы должны также придерживаться её. Также, некоторые языки придерживаются определённых договорённостей об именовании. К примеру в Java, большинство кода использует верблюжью нотацию, когда PHP в основном использует нижнее подчёркивание.

Данные правила можно совмещать. Некоторые разработчики предпочитают нижнее подчёркивание для функций и имён классов, но верблюжью нотацию для названий методов:


class Foo_Bar {

	public function someDummyMethod() {

	}

}

function procedural_function_name() {

}

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

6 - Принципы DRY

DRY - Don't Repeat Yourself (не повторяйтесь) Также известен как DIE: Duplication is Evil (повторение - зло).

Данные принципы означают:

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

Предназначение большинства приложений (или вообще компьютеров) - автоматизация повторяющихся задач. Данные принципы должны поддерживаться во всём коде, в том числе веб-приложениях. Тот же самый кусок кода не должен повторяться снова и снова.

К примеру, большинство веб-приложений состоят из множества страниц. Наверняка эти страницу будут содержать одинаковые элементы. Шапки и футеры обычно лучшие кандидаты на эту роль. Не самая лучшая идея копировать и вставлять шапку и футер на каждую страницу. Здесь Jeffrey Way объясняет как создать шаблоны в CodeIgniter.


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

$this->load->view($main_content);

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

7 - Избегайте глубокого вложения

Слишком много уровней вложения могут сделать ваш код нечитабельным.


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

8 - Ограничьте длину строки

Нашим глазам комфортно читать высокие и узкие колонки текста. Именно поэтому статьи в газетах выглядят следующим образом:

Хорошая практика - не писать длинные горизонтальные строки текста.



// 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 символов.

9 - Организация директорий и файлов

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

Во время работы над первым проектом связанным с программированием, я знал, что следует разделять код, создавать "include файлы". Однако, я совсем не был организован нужным образом. Я создал папку под названием "inc", с двумя файлами: db.php и functions.php. По мере роста функционала приложения, файл с функциями стал огромным и невероятно затруднительным в поддержке.

Один из лучших подходов - использовать фреймворк или создать определённую структуру каталогов. Вот как выглядит CodeIgniter:

10 - Последовательные временные имена

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

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



// $i for loop counters
for ($i = 0; $i < 100; $i++) {

	// $j for the nested loop counters
	for ($j = 0; $j < 100; $j++) {

	}
}

// $ret for return variables
function foo() {
	$ret['bar'] = get_bar();
	$ret['stuff'] = get_stuff();

	return $ret;
}

// $k and $v in foreach
foreach ($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 u
LEFT JOIN user_address ua ON(u.id = ua.user_id)
WHERE ua.state = 'NY'
GROUP BY u.id
ORDER BY u.username
LIMIT 0,20

12 - Разделяйте код и данные

Это очередной принцип, который подходит практически для всех языков в любой среде. В случае с веб-разработкой, "данные" представляют из себя итоговый HTML.

Изначально когда появился PHP, много лет назад, он считался шаблонизатором. Можно было увидеть большие HTML файлы с несколькими строками PHP кода. Однако, после нескольких лет ситуация изменилась, также как и веб-сайт стали всё более и более динамичными и функциональными. Теперь код является важной частью веб-приложений и его не следует объединять с HTML.

Вы можете либо применить данный принцип самостоятельно, либо воспользоваться сторонним инструментом (шаблонизатором, фреймворком или системой для управления контента - CMS) и следовать существующим договорённостям.

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

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

Популярные системы управления контентом

13 - Альтернативный синтаксис в шаблонах

Вам не обязательно использовать модный шаблонизатор, вместо него можно воспользоваться обычным PHP в ваших файлах шаблонов. Данный подход не нарушает принципа "Разделения кода и данных", до тех пор пока код отвечает за выходные данные и читабелен. В этом случае вам следует подумать об использовании альтернативного синтаксиса для управляющих конструкций.

Вот пример:


<div class="user_controls">
	<?php if ($user = Current_User::user()): ?>
		Hello, <em><?php echo $user->username; ?></em> <br/>
		<?php echo anchor('logout', 'Logout'); ?>
	<?php else: ?>
		<?php echo anchor('login','Login'); ?> |
		<?php echo anchor('signup', 'Register'); ?>
	<?php endif; ?>
</div>

<h1>My Message Board</h1>

<?php foreach($categories as $category): ?>

	<div class="category">

		<h2><?php echo $category->title; ?></h2>

		<?php foreach($category->Forums as $forum): ?>

			<div class="forum">

				<h3>
					<?php echo anchor('forums/'.$forum->id, $forum->title) ?>
					(<?php echo $forum->Threads->count(); ?> threads)
				</h3>

				<div class="description">
					<?php echo $forum->description; ?>
				</div>

			</div>

		<?php endforeach; ?>

	</div>

<?php endforeach; ?>

Это позволит вам избежать огромного количества угловых скобок. Также код выглядит, структурирован и обладает отступами подобно 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 - Чтение кода с открытым доступом

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

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

Когда вы "рефакторите", делаете изменения в коде, не меняя при этом функционал. Вы можете думать о данном процессе, как своего рода "чистке", для улучшения читабельности и качества.

Сюда не входят исправления багов или добавления нового функционала. Вы можете рефакторить код, который был написан за день до этого, пока вы всё ещё прекрасно помните, за что он отвечает, делая его более читабельным и позволяя повторно использовать, даже после того, как вы не видели его пару месяцев. Как гласит лозунг: "refactor early, refactor often (рефакторь как можно раньше, рефакторь часто)".

Вы можете применять любую из этих "лучших практик" во время процесса рефакторинга.

Я надеюсь вам понравилась эта статья! Если я что-то пропустил. Сообщите мне об этом в комментариях.