Advertisement
  1. Code
  2. HTML & CSS

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

by
Read Time:12 minsLanguages:

Russian (Pусский) translation by Anton L (you can also view the original English article)

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

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


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

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

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

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

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

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


2 - Последовательные отступы

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

Есть несколько способов добавить отступы в код.

Стиль 1:
Стиль 2:
Стиль 3:

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

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

Стиль PEAR:

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

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


3 - Избегайте очевидных комментариев

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

Когда текст очевиден, не стоит повторять его в коде, это не продуктивно.

Если вы хотите добавить комментарий для подобного кода, его следует объединить в одну строку:


4 - Группировка кода

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

Вот упрощённый пример:

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


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

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

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

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

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

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

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

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


6 - Принципы DRY

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

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

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

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

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


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

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

Ради читабельности, обычно следует изменить код, для уменьшения уровней вложенности:


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

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

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

Также, в том случае, если кто-то попытается прочитать код в окне терминала, к примеру пользователь Vim, вам следует ограничить длину строки до 80 символов.


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

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

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

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


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

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

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


11 - Заглавная буква для специальных SQL слов

Взаимодействие с базами данных - основная задача возникающая во время разработки веб-приложений. Если вы пишите непосредственно запросы SQL, также хорошо будет сделать их читабельными.

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


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

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

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

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

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

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

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


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

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

Вот пример:

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


14 - Объектно-ориентированный против процедурного подхода

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

Объекты должны представлять данные, чаще всего расположенные в базе данных.

Процедурные функции могут подойти для определённых задач, которые выполняются независимо.

15 - Чтение кода с открытым доступом

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


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

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

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

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

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

Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.