Стили кодирования и рекомендации по написанию чистого кода

Недавно наткнулся на отличную статью на хабре, решил скопипастить ее себе =) Много тут может противоречить вашим привычкам (Женя привет=))), но лично мне код должен быть еще и красиво оформлен.

Содержание

• 1 Стили кодирования
  • 1.1 Отступы
  • 1.2 Управляющие структуры
  • 1.3 Вызовы функций
  • 1.4 Определения функций
  • 1.5 Комментарии
  • 1.6 Именования
    • 1.6.1 Константы и глобальные переменные
    • 1.6.2 Встроенные константы TRUE, FALSE, NULL
    • 1.6.3 Временные переменные и «плавающие функции»
    • 1.6.4 Имена методов и свойств
    • 1.6.5 Имена классов
• 2 Рекомендации по написанию чистого кода

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

Отступы

Используйте для отступа 4 пробела, а не табуляцию.

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

Используйте фигурные скобки в управляющих структурах даже тогда, когда это необязательно:

плохой стиль:

if (isset($name)) echo "Hello $name";

хороший стиль:

if (isset($name)) { echo "Hello $name"; }

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

хороший стиль

if ((condition1) || (condition2)) {
    action1;
} elseif ((condition3) && (condition4)) {
    action2;
} else {
    defaultaction;
}

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

switch (condition) {
case 1:
    action1;
    break;

case 2:
    action2;
    break;

default:
    defaultaction;
    break;

}

Вызовы функций

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

$var = foo($bar, $baz, $quux);

Определения функций

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

function fooFunction($arg1, $arg2 = '')
{
    if (condition) {
        statement;
    }
    return $val;
}

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

function connect(&$dsn, $persistent = false)
{
    if (is_array($dsn)) {
        $dsninfo = &$dsn;
    } else {
        $dsninfo = DB::parseDSN($dsn);
    }

    if (!$dsninfo || !$dsninfo['phptype']) {
        return $this->raiseError();
    }

    return true;
}

Комментарии

Комментарии внутри кода классов должны соответствовать синтаксису комментариев PHPDoc (http://www.phpdoc.org).
Дополнительные комментарии, кроме тех, что предусмотрены PHPDoc, только приветствуются. Основное правило в данном случае — каждая часть кода повышенной сложности должна быть прокомментирована до того, как вы забыли как она работает.
Подходят комментарии в стилях C (/* */) и C++ (//). Использование комментариев в стиле Perl/shell (#) не рекомендуется.

Именования

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

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

$CACHE_PATH

Встроенные константы TRUE, FALSE, NULL

Встроенные константы PHP TRUE, FALSE and NULL должны быть написаны в нижнем регистре.

true

Временные переменные и «плавающие функции»

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

$num_elements RPC_serialize_data()

Имена методов и свойств

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

getData() $this->currentStatus

Приватные методы и свойства должны быть префиксированы знаком подчеркивания

_sort() _initTree() $this->_status

Имена классов

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

class XML_RSS {} class Text_PrettyPrinter {}

Рекомендации по написанию чистого кода

• Не использовать оператор echo для вывода html-тэгов, а использовать «встраивание» html-кода:

плохой стиль:

echo "<table>";
echo "<tr><td>Name</td><td>Position</td></tr>";
foreach ($employees as $employee) {
    echo "<tr><td>$employee[name]</td><td>$employee[position]</td></tr>";
}
echo "</table>";

хороший стиль:

<table>
  <tr><td>Name</td><td>Position</td></tr>
<?php foreach ($employees as $employee) { ?>
  <tr><td><?php echo $employee['name']; ?></td><td><?php echo $employee['position']; ?></td></tr>
<?php } ?>
</table>

• Не использовать устаревшую конструкцию = ?>

• Использование пустого пространства для усиления логической структуры кода:

плохой стиль:

$lt = localtime();
$name = $_GET['name'];
$email = $_GET['email'];
$month = $lt['tm_mon'] + 1;
$year = $lt['tm_year'] + 1900;
$day = $lt['tm_day'];
$address = $_GET['address'];

хороший стиль:

$name    = $_GET['name'];
$email   = $_GET['email'];
$address = $_GET['address'];

$lt    = localtime();
$day   = $lt['tm_day'];
$month = $lt['tm_mon'] + 1;
$year  = $lt['tm_year'] + 1900;

• Использование пустого пространства для усиления логической структуры SQL-запросов:

плохой стиль:

$query = "SELECT FirstName, LastName FROM employees, departament WHERE employees.dept_id = departament.dept_id AND departament.Name = 'Engineering'";

хороший стиль:

$query = "SELECT firstname, lastname FROM employees e, departament d WHERE e.dept_id = d.dept_id AND d.name = 'Engineering'";

• Всегда используйте include_once() gt;clients[$clientID]-и require_once() вместо include() и require()

• Всегда используйте вместо ?> для выделения PHP-кода

• Когда строка является литеральной (не содержит подстановок переменных), для ее обрамления должны использоваться апострофы или «одинарные кавычки»:

$a = 'Example String';

• Функции в глобальной области видимости («плавающие функции») допустимы, но не приветствуются. Рекоммендуется обрамлять такие функции в статические классы.