Перепечатка статьи от 14.02.2009

Уже давно хотел собрать воедино все что связано непосредственно с оформлением кода и стандартами напсиания кода. И вот наконец-то предоставилась такая возможность.
Данные стандарты практически полностью базируются на Стандартах кодирования PEAR (http://pear.php.net/manual/ru/standards.php). Однако есть ряд изменений и дополнений.

Стандарты кодирования

Содержание

1. Отступы

2. Управляющие структуры (if, else, switch)

3. Вызовы и определения функций

4. Комментарии

5. Подключение кода (including)

6. Тэги PHP-кода

7. Соглашения об именах

1. Отступы

Используйте для отступа 4 пробела, а не табуляцию. Если вы используете Emacs для редактирования кода, вы должны установить indent-tabs-mode в ноль. Ниже приведен пример настройки Emacs для этой цели:

А это пример конфигурации для редактора VIM:

Также рекомендуется делать отступы до и после оператора конкатенации. Пример:

2. Управляющие структуры

Управляющие структуры включают в себя операторы if, for, while, switch, и др. Ниже приведен пример оформления оператора if, который в этом отношении является самым сложным:

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

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

Cинтаксис оператора switch:

3. Вызовы и определения функций

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

Как можно заметить, в примере используются пробелы с двух сторон от знака «=». Если подобные присвоения результатов функций переменным объединяются в блоки, то для повышения читабельности рекомендуется следующий синтаксис:

Определения функций следуют такому cоглашению:

Аргументы функций со значениями по умолчанию должны находиться в конце списка аргументов. Функции всегда должны возвращать значение, если это возможно в принципе. Чуть более подробный пример:

4. Комментарии

Подходят комментарии в стилях C (/* */) и C++ (//). Использование комментариев в стиле Perl/shell (#) не рекомендуется.

5. Подключение кода (including)

Всегда используйте include_once() и require_once() вместо include() и require() для того чтобы быть увереными в том, что файлы подключаются только единожды.

Так как include_once() и require_once() являются конструкциями, а не функциями, то не обязательно использовать скобки вокруг имени файла, который подключается.

6. Тэги PHP-кода

Всегда используйте <?php ?> вместо <? ?> для выделения PHP-кода. Это необходимо для обеспечения работы PEAR на разных операционных системах и с различными настройками.

Короткие тэги разрешается использовать только лишь в шаблонах представления (php и tpl шаблонах)

7. Соглашения об именах

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

Имена временных переменых должны быть короткими и лаконичными. В частности числовые переменные, которые используются для итерации, могут называться: i, j, k, l, m, n и т.д.

Имена состоящие из нескольких слов

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

Константы и глобальные переменные

Имена глобальных переменных и констант следует вводить в верхнем регистре. Это позволяет легко идентифицировать их как глобальные переменные.

Классы

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

пример описания класса: