Оформление кода PHP: стандарты и правила

Следование единым правилам упрощает работу программистов. Оформление кода PHP по одному стандарту помогает в командной работе и повышает уровень разработки. Понятие «качественный код» появилось не случайно, так же, как и анекдоты о неспособности спустя время прочитать даже собственный код. Понятный структурированный код сокращает время чтения, позволяет сразу приступить к поиску проблемы.

Восемь общих правил

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

1. Придумывайте понятные и читаемые названия. Избегайте русских слов в латинской транскрипции. Только английские слова, обозначающие суть.
2. Делайте отступы на каждом уровне и отделяйте логические блоки пустой строкой.
3. Сокращайте вложенность кода и убирайте дублирование.
4. Контролируйте длину. Рекомендуем для функций не более 20 строк, для метода не более 50 строк, для класса не более 300 строк, для файла — не более 1000 строк. Также ограничивайте длину одной строки до видимого значения на экране. Мягкое ограничение составляет 120 символов.
5. Комментируйте и документируйте код. Это позволит зафиксировать всю необходимую информацию.
6. Используйте рефакторинг. Следуйте принципу «рефакторинг — раньше и рефакторинг — чаще». Советуем также прочитать книгу «Рефакторинг. Улучшение проекта существующего кода» Мартина Фаулера.
7. Работайте в системе контроля версий, например, Git. Это бесплатно и удобно. Обучиться работать в ней можно за 11 занятий на видеокурсе «Git. Быстрый старт».
8. Изучайте Open Source код. Вы сможете увидеть, как пишут ведущие разработчики и воспользоваться лучшими практиками в программировании.

Правила кода PHP

На конец 2017 г. действуют стандарты PHP программирования: PSR-2 и PSR-1. Они устанавливают правила синтаксиса, именования, оформления. Весь код должен быть написан единообразно. Это касается пробелов, отступов, скобок, строк.

Чтобы не запоминать все требования стандартов, можно работать в современной среде разработки — PhpStorm, NetBeans и подобных. Они позволяют автоматически форматировать текст в соответствии с правилами.

Отступы

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

Запомните: один отступ = четыре пробела.

Выделяем отступами тело конструкции, тело метода, блоки импорта, аргументы и подобное.

Правильно

<?php
switch ($expr) {
   case 1:
       echo `One`;
       break;
   case 2:
       echo `Two`;
       break;
   }
?>

Неправильно

<?php
 switch($expr)
{
          case1:
     echo `One`;
           break;
   case 2:
              echo `Two`;
   break;    }
?>

Пробелы

Ставятся:

• между for ( foreach/  while / catch) и (
• после ;
• между ) и {
• перед =>
• после =>
• между try и {
• между } и catch

Не ставятся:

1. После имени метода.
2. В списке аргументов перед запятыми.
3. Между ( и именем функции или метода.

Пустая строка

Вставляется:

1. После каждого логического блока.
2. После определения пространства имен.
3. После блока импорта. Каждая строка блока должна начинаться с use.

Правильно

<?php
      namespace Vendor\Package;

     use FooClass;
     use BarClass as Bar;
     use OtherVendor\OtherPackage\BazClass;

    // …
?>

Неправильно

<?php
      namespace Vendor\Package;

     use FooClass; use BarClass as Bar;
     use OtherVendor\OtherPackage\BazClass;

    // …
?>

Круглые скобки

1. Не выносим на отдельные строки.
2. Не ставим пробелы внутри: после ( и перед ).
3. Ставим пробелы до скобок и после.
4. Внутри перечисление отделяем пробелами.

Фигурные скобки

1. Открывающая фигурная скобка выносится на новую строку перед телом метода, для классов.
2. Открывающая фигурная скобка не выносится на отдельную строку в конструкциях и замыканиях.
3. Закрывающая скобка } в конструкциях, имени метода, определении метода, классах пишется с новой строки и отделяется одним отступом.

Аргументы

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

Правильно

<?php
    Foo: :bar($arg1, $arg2, $arg3);
?>

Неправильно

<?php
    Foo: :bar($arg1   , $arg2,$arg3);
?>

При оформлении в столбик каждый аргумент пишется с новой строки и отделяется двойным отступом. Первая круглая скобка остается на строке вместе обозначением метода. Вторая круглая скобка выносится в отдельную строку вместе с открывающей фигурной скобкой. Между ними пробел.

Правильно

<?php
    $foo ->bar(
        $firstArgument,
        $secondArgument,
        $thirdArgument
    );
?>

Неправильно

<?php
    $foo ->bar(
        $firstArgument,
        $secondArgument,
        $thirdArgument);
?>

Конструкция switch case

Конструкцию делим на три уровня: switch, case, echo/break. Каждый уровень начинается с отступа. Таким образом, наш код визуально выглядит состоящим из трех столбцов.

Если в конструкции не используется break, поставьте // no break.

Правильно

<?php
    switch ($expr) {
        case 0:
            echo `First case, with a break`;
            break;
        case 1:
            echo `Second case, with fall through`;
            // no break
        case 2:
        case 3:
        case 4:
            echo `Third case, return instead of break`;
            return;
        default:
            echo `Default case`;
            break;
    }
?>

Неправильно

<?php
    switch ($expr) {
        case 0:
            echo `First case, with a break`;
            break;
        case 1:
            echo `Second case, with fall through`;
        case 2:
        case 3:
        case 4:
            echo `Third case, return instead of break`;
            return;
        default:
            echo `Default case`;
            break;
    }
?>

Конструкция try catch

Тело try  и тело catch отделяются одним отступом. Пробелы нужно поставить:

• между try и {
• между } и catch
• между catch и (
• между ) и {

Catch и скобку } ставим на одну строку.

Правильно

<?php
   try {
        // тело try
        } catch (FirstExceptionType $i) {
        // тело catch
    } catch (OtherExceptionType $i) {
        // тело catch
    }
?>

Неправильно

<?php
try {
     // тело try
        } 
catch (FirstExceptionType $i) 
{
        // тело catch
 } catch (OtherExceptionType $i) {
        // тело catch     }
?>

Конструкция if, elseif, else

Операторы и открывающую фигурную скобку пишем на одной строке. Закрывающую фигурную скобку оператора пишем на той же строке, что и оператор. Заключительную фигурную скобку пишем на отдельной строке. Оператор else if пишем как единое слово - elseif. Тело оператора отделяем отступом.

Правильно

<?php
    if ($a == $b) {
        echo `A равно B`;
    } elseif ($a == $c) {
        echo `A равно C`;
    } else {
        echo `A ничему не равно`;
    }
?>

Неправильно

<?php
    if ($a == $b) {
        echo `A равно B`;
    } else if ($a == $c)
 {
        echo `A равно C`;
    } else 
{
        echo `A ничему не равно`;
    }
?>

Комментарии в коде

Чистый код должен быть правильно закомментирован. К сожалению, встречаются две крайности: подробное комментирование каждой строки и полное отсутствие комментариев. И то, и другое мешает в работе. Избыточное комментирование снижает восприятие кода, отвлекает от понимания его сути. Писать очевидные вещи — тратить свое и чужое время. Иногда из-за слишком подробных комментариев объем кода увеличивается в несколько раз. Закончив с кодом, посмотрите критически. Очевидные и банальные комментарии удалите.

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

Больше информации о комментариях вы найдете в статье «Почему комментарии в коде — зло». А если вы считаете, что код - не место для шуток, предлагаю подборку самых забавных комментариев программистов.

Чек-лист «Инспекция кода»

Предлагаем чек-лист для самостоятельной проверки чистоты кода. Если вы будете инспектировать чужой код, помните, что программист — творческая профессия. А творческие люди обычно тяжело воспринимают критику. Будьте лояльней.

Итак,

• Легко ли воспринимать код визуально?
• Присутствуют ли комментарии? насколько они необходимы?
• Соответствует ли код стандартам PSR-1 и PSR-2? Краткая выжимка стандартов приведена в разделе “Правила кода PHP”.
• Используете ли вы систему документирования phpDoc или подобную?
• Нужно ли делать перерыв в чтении, чтобы разобраться в написанном?
• Проведен ли рефакторинг?
• Есть ли дублирование в блоках, функциях и пр.?
• Понятны ли названия переменных, имена методов и пр.?
• Какова длина строк, методов, функций, классов, файла?
• Вы искали ошибки и баги?
• Как можно еще улучшить код?
• Можно ли сделать его короче?
• Можно ли сделать его эффективней?

Желательно провести тестирование. Руководствуйтесь тремя принципами:

1. Тесты должны быть полными.
2. Тесты должны соответствовать установленным требованиям.
3. Тесты должны проводиться на нужном уровне тестирования.

Дополнительную информацию по тестированию вы найдете в материале «Тестирование кода для чайников».

Заключение

Код — это не личный захламленный ящик с грудой бумаг. Правильный код — это картотека в Ленинской библиотеке. В нем все структурировано, задокументирована важная информация, есть связи с другими каталогами и библиотеками. Чистый код может разобрать и профи, и начинающий программист. С ним приятно работать, он характеризует уровень мастерства своего разработчика.

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