Правила оформления программного кода

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

PHP Coding Standard;
C++ Coding Standard;
Соглашения по оформлению кода команды RSDN.
Стандарт кодирования на PHP в Zend Framework'е (добавлено 10.02.2007)

Мои же рекомендации касаются в основном читабельности кода. Для PHP это особенно важно, так как на одной странице часто смешивается и выполняющийся на сервере программный код, и вывод HTML, и сценарии JavaScript. Чтобы все это не превратилось в кашу, в которой даже создатель через некоторое время не в силах разобраться, полезно придерживаться следующих правил.

Главное правило

В начале любого файла с кодом всегда оставляйте информацию о его назначении, авторе (желательно с контактным e-mail'ом) и дате создания.


<?php
############################################
# ВЫВОД ИНФОРМАЦИИ О ТОВАРАХ
#
# Файл создан: 23.11.2006
# Автор: Юрий Кошаровский
# E-mail: info@yukosh.ru
############################################
?>

Для «коробочных» продуктов возможно применение более навороченных схем, например таких:


<?php
/*======================================================================*\
|| #################################################################### ||
|| # vBulletin 3.5.4 - Licence Number FKC009AF94                        ||
|| # ---------------------------------------------------------------- # ||
|| # Copyright ©2000-2006 Jelsoft Enterprises Ltd. All Rights Reserved. ||
|| # This file may not be redistributed in whole or significant part. # ||
|| # ---------------- VBULLETIN IS NOT FREE SOFTWARE ---------------- # ||
|| # http://www.vbulletin.com | http://www.vbulletin.com/license.html # ||
|| #################################################################### ||
\*======================================================================*/
?>

Оформление синтаксический конструкций

Правило 1. Не используйте пары фигурных скобок в одной строке. Даже если в них заключается всего одна инструкция.


<?php
// Правильно
if ($x == 1) {
    echo "OK";
}

// Неправильно
if ($x == 1) { echo "OK"; }
?>

Правило 2. Не игнорируйте фигурные скобки, даже если синтаксические правила языка позволяют это сделать.


<?php
// Правильно
if ($x == 1) {
    echo "OK";
}

// Неправильно
if ($x == 1) echo "OK"; 
?>

Правило 3. Синтаксис (expr1) ? expr1 : expr2 не отличается хорошей читабельностью, поэтому его следует использовать крайне аккуратно и не слишком часто. Используйте подобную конструкцию для вывода коротких строк или присвоения значений переменным.


<?php
// Допустимо
echo ($i%2 == 0) ? "#000000" : "#FFFFFF";
$color = ($i%2 == 0) ? "#000000" : "#FFFFFF";

// Недопустимо
($i%2 == 0) ? $color = "#000000" : $color = "#FFFFFF ";

// Еще хуже
$b = 4;
$c = 6;
$a = ($b == 4) ? ($c == 0) ? "value1" : "value2" : "value3"; //синтаксически вполне правильная конструкция
?>

Правило 4. Формальные и фактические параметры функции отделяются друг от друга запятой и пробелом, а не одной запятой.


<?php
// Правильно
number_format($number, 2, ",", " ");
function MyHandler($error, $message) {
    // какой-то код
}

// Неправильно
number_format($number,2,","," ");
function error_handler($error,$message) {
    // какой-то код
}
?>

Правило 5. Операторы пишутся с пробелами с двух сторон. Исключением может быть только точка — оператор конкатенации.


<?php
// Правильно
$a = ($c + $d) * 3;

// Допустимо
$string = "Сегодня ".date("d")." число";

// Неправильно
$a=($c+$d)*3;
?>

Как правильно смешивать PHP и HTML-код

Правило 6. Функции echo и print следует применять как можно реже. Используйте их для вывода отладочной информации или очень небольших фрагментов текста. Недопустимо выводить таким образом большие куски HTML-кода, да еще совмещая его с переменными или функциями PHP.


<?php
// Допустимо (небольшой фрагмент текста)
echo "Сегодня ".date("d")." число";

// Допустимо (отладочная информация)
if ($a == 1) {
    echo "true";
    // какой-то код
}
else {
    echo "false";
    // какой-то код
}
?>

<!-- А лучше так -->
Сегодня <?=date("d")?> число

<?php
// Недопустимо
echo "<table><tr><td>Марка</td><td>Модель</td></tr><tr><td>$brand</td><td>$model</td></tr></table>";
?>

Правило 7. Вставка переменных или функций PHP в HTML-код осуществляется при помощи тегов <?= ?>.


<?php
// Правильно
$date = date("d").".". date("m").".". date("Y");
?>
<h1>Привет, сегодня у нас <?=$date?></h1>

<?php
// Неправильно
echo "<h1>Привет, сегодня у нас ".$date."</h1>";

// За такое вообще убивать надо
echo "<h1 class=\"my_h1\">Привет, сегодня у нас ".date("d").".". date("m").".".date("Y")."</h1>";
?>

Правило 8. Правило 7 действует также при выводе значений в цикле.


<!-- Правильно -->
<table>
    <tr>
        <td>Марка</td>
        <td>Модель</td>
    </tr>
    <?php
    foreach ($cars as $brand => $model) {
        ?>
        <tr>
            <td><?=$brand?></td>
            <td><?=$model?></td>
        </tr>
        <?php
    }
    ?>
</table>

<!-- Неправильно -->
<table>
    <tr>
        <td>Марка</td>
        <td>Модель</td>
    </tr>
    <?php
    foreach ($cars as $brand => $model) {
        echo "
        <tr>
            <td>".$brand."</td>
            <td>".$model."</td>
        </tr>";
    }
    ?>
</table>

<?php
// А некоторые делают так. Расстрел на месте
echo "
<table>
    <tr>
        <td>Марка</td>
        <td>Модель</td>
    </tr>";
    foreach ($cars as $brand => $model) {
        echo "
        <tr>
            <td>".$brand."</td>
            <td>\"".$model."\"</td>
        </tr>";
    }
echo "</table>";

Правило 9. Открывающие и закрывающие теги PHP также подчиняются правилам расстановки отступов и логике программы.


<?php
foreach ($cars as $brand => $model) {
    // закрывающий тег сдвинут вправо, так как следует после foreach
    ?>
    <!-- HTML-код находится на одном уровне с тегами PHP, так как логически им не подчиняется -->
    <tr>
        <td><?=$brand?></td>
        <td><?=$model?></td>
    </tr>
    <?php
}
?>