Блог


Стиль кодирования (продолжение)

 

Начало здесь.

Я уже рассказал об основных соглашениях. Есть еще много маленьких мелочей, делающих код приятным и читабельным. По поводу них много разных споров и религиозных войн, так что я буду пытаться обосновывать каждую свою рекомендацию. а вы уже выбирайте. Стиль кодирования, это не 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

 

Теги: MySQL | ajax | PHP

Комментарии (11)

Savage
19-03-2013
Про пробелы после операторов логично, да и по правде говоря они как-то лишними и казались. Просто непонятно, зачем такой стиль применяют, например руководители софттайма в своём творчестве, написано, что они профессионалы в IT-области. Кто им привил такой стиль интересно? ))

А про точку после апострофа как-то даже и не задумывался, ставил пробел и не казалось, что их как-бы два. Если присмотреться, то мне кажется, что процентов так 10-12 лишнего добавляется. Вообще одним пробелом меньше и это хорошо.

п.с. ссылка "Начало здесь." нотисы выдаёт, нет перехода.
Savage
19-03-2013
Странно, что после написания комментария jpeg-и в статье пропали.
Savage
19-03-2013
Ну да, нажимаю "Написать комментарий" и jpeg-и не отображаются. Закрываю форму (переход назад) и опять на месте.
twin
19-03-2013
TinyMCE чудит. Не хочет ссылки абсолютные делать. Сейчас поправим.
Savage
20-03-2013
Работает !
Andrey
06-06-2013
В Netbeans есть подсветка переменных, ежели писать так    
$sql = ' SELECT ' . $select . ',
                  DATE_FORMAT(date, "%d") AS day,
                  DATE_FORMAT(date, "%m") AS month,
                  DATE_FORMAT(date, "%Y" ) AS year
                   FROM blog_comments
                    WHERE id_blog ="' . $this->LINK->real_escape_string($row['id']) . '"
                     AND publish = 1
                      ORDER BY id ' . $this->CONF['BLOG_PAGE_COMMENTS_SORT']) . '
                       LIMIT ' . $this->pag . ' ';

Хотелось бы от вас услышать по поводу обратных кавычек(`) - для чего их рекомендуют использовать?
twin
06-06-2013
Подсветка есть не во всех редакторах. Это раз. Ваш запрос работать не будет, потому что кое где нужно экранировать апострофы, это два. А про обратные кавычки - я советовал бы изучить синтаксис SQL. Откроете очень много нового и интересного.
АНДРЕЙ
06-06-2013
Яж говорю про Netbeans. Код этот работал и работает(какие апострафы, где?)
Почему это он не будет работать?
twin
06-06-2013
А причем тут  Netbeans? Если писать только для себя, нет вопросов. Хоть в одну строку. Речь идет о публичном стиле. Последователи не обязательно будут им пользоваться.

А про код, так вот это место как понимать?

id_blog ="' . $this->LINK->real_escape_string($row['id']) . '"

Литеральные константы по требованиям синтаксиса SQL должны обрамляться апострофами, а не двойными квычками.
andrey
07-06-2013
Гдето по тексту было сказаночто не все подсвечивают(просто привел пример нетбинс). Я сам незнал что оно подсвечиваемо - зашел на их форум посмотрел пример...
Незнаю работает без апострафов. И на локальном сервере и на хостинге.
Чесно говоря я непомню по какой причине я впердолил туда двойные кавычки(пример за прощлый год). Работает и с ними и без.

зы на кнопочку "ответить" нажать не могу
twin
08-06-2013
Работть будет до поры до времени. Я бы советовал бросить метод тыка и начать изучать синтаксис.

 
Наверх