Стили кодирования и рекомендации по написанию чистого кода
Недавно наткнулся на отличную статью на хабре, решил скопипастить ее себе =) Много тут может противоречить вашим привычкам (Женя привет=))), но лично мне код должен быть еще и красиво оформлен.
Содержание
-
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 "
| Name | Position |
| $employee[name] | $employee[position] |
хороший стиль:
| Name | Position |
- Не использовать устаревшую конструкцию
- Использование пустого пространства для усиления логической структуры кода:
плохой стиль:
$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';
- Функции в глобальной области видимости («плавающие функции») допустимы, но не приветствуются. Рекоммендуется обрамлять такие функции в статические классы.