Как оформлять код?

В этой статье описан стиль оформления кода используемый во фреймворке.

  1. Переменные, значения которых получены извне (от клиента), должны иметь префикс "$ext_". Сокращение от слова external – внешний, что подразумевает внешние данные. Такое именование переменных, даёт наглядность при чтении кода и указывает на то, что значение переменной получено извне.

    $ext_id = get_int('id');
    
    $ext_name = get_str('name');​
  2. Было решено не использовать $_POST и $_GET, всегда используется $_REQUEST. А при настройке PHP ini_set('request_order', 'GPC'), в $_REQUEST будут попадать значения из массива $_COOKIE - это может быть очень удобно! Это делает код более масштабируемым, ведь для разработчика не должно быть разницы, откуда поступают данные, главное их проверка и правильный приём.

    Для приёма внешних данных используются функции, get_int(), get_str() и т.п. Поэтому прямое обращение к $_REQUEST в простых случаях не используется.

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

    // Пример: вставка одной записи.
    $sql = 'INSERT INTO ?_users SET';
    $sql.= ' Name = ?,';
    $sql.= ' Age = ?d,';
    $sql.= ' Email = ?';
    
    // Пример: обновление записи.
    $sql = 'UPDATE ?_users SET';
    $sql.= ' Name = ?,';
    $sql.= ' Age = ?d,';
    $sql.= ' Email = ?';
    $sql.= ' WHERE id = ?d';
    
    // Пример: HTML-текст.
    $html = '<table>';
    $html.= '<tr>';
    $html.= '<td>';
    // $html.= 'Старый компьютер.';
    $html.= 'Новый компьютер.';
    $html.= '</td>';
    $html.= '</tr>';
    $html.= '</table>';​

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

    $html = '<table>
    	<tr>
    	<td class="cal_header" colspan="7">' . $month_str . ' ' . $year . '</td>
    	</tr>
    	<tr>
    		<td class="weekday">ПН</td>
    		<td class="weekday">ВТ</td>
    		<td class="weekday">СР</td>
    		<td class="weekday">ЧТ</td>
    		<td class="weekday">ПТ</td>
    		<td class="weekday">СБ</td>
    		<td class="weekday">ВС</td>
    	</tr>
    	</table>';
  4. Строки окружаются в ' (single quote), а параметры внутри строк в " (double quote).

    // Пример: HTML-текст, тэг <div> с параметрами.
    $html = '<div style="color: red;">...</div>';
    
    // Пример: SQL-запрос, значение параметра name в двойных кавычках.
    $sql = 'SELECT * FROM users WHERE name LIKE "..."';​
    
    // А этот вариант ОЧЕНЬ плохой :(
    $str = "Возраст $age";
    
    // А этот хороший!
    $str = 'Возраст ' . $age;
  5. Стиль конкатенации строк для PHP. Для JavaScript используется подобный подход.

    // Правильный стиль конкатенации частей многострочной строки.
    // Сперва должна идти инициализация строки с пустым значением.
    
    $str = '';
    $str.= 'SELECT * FROM any_table WHERE';
    $str.= ' id = 123';
    
    // Правильный стиль суммирования в цикле.
    $total_sum = 0;
    
    while( $records as $record ){
    
    	// Пробел перед +=
    	$total_sum += $record['retail_price'];
    
    	// или так
    	$total_sum = $total_sum + $record['retail_price'];
    	
    }
    
    // Правильный стиль суммирования, для случая, когда строки идут подряд.
    
    $total_sum = 0;
    $total_sum+= $delivery_cost;
    $total_sum+= $pack_cost;
    $total_sum+= $goods_cost
    
    
    // Не правильный стиль. Для строк идущих подряд, не должно быть пробела перед .=
    $str = '';
    $str .= 'SELECT * FROM any_table WHERE';
    $str .= ' id = 123';
    
    
    // Не должно быть пробела перед +=
    $total_sum = 0;
    $total_sum += $delivery_cost;
    $total_sum += $pack_cost;
    $total_sum += $goods_cost
    ​
  6. Переменные в PHTML-шаблонах (PHP + HTML).

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

    <html>
    	<body>
    		<?=$vars['content'];?>
    	</body>
    </html>​​

    "Плохой" стиль

    <html>
    	<body>
    		<?php echo $vars['content']; ?>
    	</body>
    </html>​
  7. Начало и конец PHP-скрипта.

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

    <?
    
    // Код и комментарии первого уровня вложенности, должны быть на уровне с открывающим и закрывающим тегом PHP.
    $cost_per_km = 10;
    
    function hello_world(){
    
    	// А этот код и комментарий, уже будут иметь отступ в соответствии со своей иерархией. 
    	return true;
    
    }
    
    ?>​

    Плохой стиль

    Писать полный открывающий тег - незачем, а не писать закрывающий тег - плохо. Делать отступ для кода с иерархией первого уровня - плохо!

    <?php
    
    	// Код и комментарии первого уровня вложенности, должны быть на уровне с открывающим и закрывающим тегом PHP.
    	$cost_per_km = 10;
    
    	function hello_world(){
    
    		// А этот код и комментарий, уже будут иметь отступ в соответствии со своей иерархией. 
    		return true;
    
    	}
    
    
  8. В качестве отступов используются и должны быть использованы (в PHP, JS, CSS, HTML и любом другом текстовом и скриптовом файле) только символы табуляции, всё остальное от беса :) Отступы пробелами - очень плохо!

 

© Автор и разработчик Михаил Шершнёв, 2006–2021
E-mail: support@bwframework.ru