Начало здесь.
Я уже рассказал об основных соглашениях. Есть еще много маленьких мелочей, делающих код приятным и читабельным. По поводу них много разных споров и религиозных войн, так что я буду пытаться обосновывать каждую свою рекомендацию. а вы уже выбирайте. Стиль кодирования, это не RFC, тут нет жестких стандартов. Просто нужно стараться писать так, чтобы другим было приятно читать.
Приступим.
Первое - не нужно лепить код к левому краю, делайте отступ в 4 пробела. Люди не зря придумали паддинг, без него текст читается не комфортно, а код, это тот же самый текст. Это психология или даже физиология, если угодно. Прежде чем начать говорить, человек должен сделать вдох. Иначе ему просто не хватит воздуха. Отступ от края дает возможность сделать этот психологический вдох и дискомфорт пропадает.
Кроме того, есть еще и технические обоснования отступа. В некоторых редакторах есть инструмент, показывающий блоки. Есть он и в нашем редакторе. Если прилепить код к левому краю, он теряет смысл. И второе, в школьных тетрадях есть поля. Это не просто так, это специальное место для пометок. Так вот отступ в коде - те же самые поля. Туда удобно писать временные комментарии и отладочный код. Сразу видно, где код рабочий, а где временный:
С отступами код становится чистым, воздушным, так и просится в работу. Единственно где не нужно отступов, это в классах. Класс, это область видимости, просто границы. Совершенно незачем отслеживать его начало и конец, это тоже самое, что обозначать начало и конец файла. Кстати, есть еще одно железное правило. Один класс - один файл. Ни разносить по файлам, ни писать больше одного класса в файл нельзя. За редким исключением, когда есть вспомогательные классы, которые используются только и только с основным. Ни где иначе.
Дальше. Если в блоке идет последовательно присваивание значений переменным, выравнивайте знаки. Да и не только присваивание. Все, что можно выровнять - выравнивайте. Человек любит симметрию и геометрическую правильность. А значит "ровный" код ему читать приятнее. Сравните сами:
1
2
3
4
5
6
7
8
9
10
|
$num_page = 1;
$count_array = count($array);
$leter = 'S';
$string = 'Example';
$sleep = 5;
$data_works = getDataWorks();
|
Нервотрепка какая то, а не код. А вот так песня:
1
2
3
4
5
6
7
8
9
10
|
$num_page = 1;
$count_array = count($array);
$leter = 'S';
$string = 'Example';
$sleep = 5;
$data_works = getDataWorks();
|
Особенно хорошо смотрится выравнивание в массивах:
1
2
3
4
5
6
7
8
9
10
11
12
|
/**
* Errors of performance of the program.
* @var array
*/
public $mailererrors = array(
'no_text' => 'There is no message text',
'no_file' => 'The path to a file is not specified',
'no_path' => 'There is no file on the specified path',
'no_addresse' => 'There is no addresse',
'not_correct' => 'The e-mail address is not correct',
'no_sender' => 'There is no sender',
'no_theme' => 'There is no theme',
'no_send' => 'For technical reasons letter sending
is impossible at present',
);
|
Дальше поехали. Часто можно встретить код, в котором круглая скобка отделяется от названия функции пробелом. Это тоже противоречит человеческой природе. Левитация какая то. Функция должна взять аргумент, а он повис рядом с ней в воздухе. Как будто я не я и лошадь не моя:
1
2
3
4
5
6
|
$var = getVar ($data);
if ($num == 1)
{
|
Я не зря написал еще и оператор. Часто можно встретить такие рекомендации, что в функциях пробел не нужен, а в операторах и циклах нужен. А в чем собственно сакраментальная разница? В том, что функция производит действие где-то за кадром, а операторы и циклы не отходя от кассы? Суть то не меняется. Оператор должен что-то делать, управлять железною рукою, а его подчиненные разбежались кто куда по странице.
Еще раз повторю, код, это осмысленный набор фразеологических единиц. Слов другими словами (тавтология). А значит это текст. А текст должен подчиняться правилами его написания. И если оператор , это единое со скобками слово, пробел ломает все стереотипы и делит его на два. Я могу еще понять, когда пробелы ставят внутри скобок, хотя и этого не рекомендую (объясню чуть позже). Но рвать пополам оператор, это зря.
Любой пробел, это пуза. Скажите про себя фразу "Если я буду писать стилизованный код, то стану профессионалом". Паузы между "Если" и определяющим блоком практически нет. А теперь так:
"Если
я буду писать стилизованный код, то стану профессионалом"
Суть вроде бы одна, но с паузой звучит как то неуверенно. Тоже самое и про пробелы внутри круглых скобок. Скобки по своей сути создают границы, связывают код, должны держать его крепко, не выпуская за рамки дозволенного. А пробелы создают "люфт" и неуверенность. Открыли скобку и задумались, зачем открыли... Может и не надо было... Действия должны быть решительными. Достал пистолет - стреляй. Нечего рассусоливать.
Дальше. Кавычки. Есть два вида организации литеральных констант (строковых значений). Двойные кавычки и апострофы. Правила просты, если в строке не предполагаются служебные символы, нужно использовать апостроф. Если нужны переносы к примеру - двойные кавычки. Апострофы смотрятся свободнее и изящнее, не загружают год излишней пестротой. Еще в двойных кавычках интерпретируются переменные, но не нужно этого делать. Дело в том, что не все редакторы подсвечивают переменные внутри кавычек. И читать его становится полным мучением.
1
2
3
4
5
6
|
echo 'Привет, Мир!'; // Апострофы почти незаметны, не отвлекают от сути
echo "<br>\r\n"; // Служебные символы работают только в двойных кавычках
echo "Сумма: $summ "; // Нечитабельно
echo 'Итого: '. $total; // Так длиннее, но насколько проще читать.
|
Теперь о конкатенации, раз заговорили. Обратите внимание на отделение пробелами знака конкатенации (точки). Со стороны апострофа пробела нет. А со стороны переменной есть. Я рекомендую именно такую форму.
Почему так. В полиграфии есть понятие "кернинг". Это избирательное изменение интервала между буквами в зависимости от их формы. Вот смотрите. Буквы "у" и "ш" имеют разную ширину. Текст начинает скакать. Кроме того, буква "у" внизу завернута влево. А допустим "ч" - вправо. Если поставить их рядом и сделать одной ширины, получится ощущение пробела между ними. Ну а что говорить о латинице с её i, f, m, w и так далее.. Для устранения этого психологического дискомфорта придуман кернинг. Промежутки между буквами не одинаковые, они зависят от самих букв и их расположения в слове. Это целая наука.
Если написать урок моноширинным текстом, учиться будет гораздо сложнее.
Чувствуете дискомфорт?
Так вот и с конкатенацией тоже самое. Апостроф и кавычка находятся сверху строки. Под ними пустота. А точка наоборот - снизу. Поэтому создается ощущение пробела. Если поставить туда пробел, будет ощущение двух.
Ну и последнее, что очень важно. Стиль написания запросов. Обычно редакторы подсвечивают какой то один код, PHP или SQL, очень редко вместе. Так как основной код пишется на PHP, SQL обречен быть одноцветным. Но как то выкручиваться и повышать читабельность нужно. Для этого есть одно простое правило. Названия таблиц, полей и алиасов пишем в нижнем регистре, все операторы и служебные команды - в верхнем. Таблицы и поля нужно обрамлять обратными кавычками. Алиасы и префиксы не надо.
Это может на первый взгляд показаться форменным издевательством над организмом, ведь SQL допускает написание кода в любом регистре. Но когда выработается привычка, профит не заставит себя ждать. Код становится намного читабельнее и интуитивно понятнее. А программисту время дорого, зачем его тратить на разбор нечитабельного кода, когда можно срезаться в Доту.
Второе правило, не вытягивайте SQL в одну линию и не объединяйте их конкатенацией. Переносите клаузы построчно. Причина банальна - интерпретатор SQL так же как и PHP выдает номер строки с ошибкой. А если вы используете нашу обертку, то понять где она, особенно в большом запросе, гораздо проще.
И третье. SQL в листинге PHP нужно обрамлять двойными кавычками. Это потому, что внутри них просто и без слэшей пишутся апострофы, а они являются очень важной частью SQL синтаксиса.
А вот и виновник торжества, идеально написанный по нашей версии код (правда с ошибкой ;) ):
1
2
3
4
5
6
7
8
9
10
11
12
13
14
|
public function setModification()
{
mysqlQuery("UPDATE `". $this->table ."`
SET `". $this->sorts ."` =
(SELECT @i := @i + 1
FROM (SELECT @i := MAX(`". $this->sorts ."`)
FROM `". $this->table ."`
". $this->where ."
) AS a
)
WHEPE `". $this->sorts ."` = 0
". $this->and
);
}
|
Ну вот кажется и все. Остальные незначительные мелочи - дело вкуса. Главное писать код, как хороший роман. Помните, писатель один, а читателей куча. Если написано хорошо, почитателей много. Если абы как - фтопку.
Николай aka twin
Роман