Хороший стиль программирования ч.2

PHP собрал в себе практически все комментарии современных языков программирования, наряду с однострочными комментариями в стиле shell-скриптов (#)

<?php
# Программный модуль index.php
echo "Hello world!";
?>

и С++ (//)

<?php
// Программный модуль index.php
echo "Hello world!";
?>

можно использовать многострочный комментарий в стиле C:

<?php
/* Это многострочный комментарий в стиле С
он охватывает несколько строк – не допускается
вложенных комментариев
*/
echo "Hello world!";
?>

К хорошему тону относится использование однострочных комментариев для короткого комментария, а многострочного — для комментария, охватывающего несколько строк. Не возбраняется использовать однострочные комментарии для большого текста, особенно в начале файла или важного блока кода

<?php
////////////////////////////
// Гостевая книга
////////////////////////////
?>

Как и при работе с отступами и фигурными скобками, основным требованием является необходимость придерживаться одного стиля во всех программных блоках.
При расстановке однострочных комментариев возможно два варианта: непосредственно перед выполняемым оператором

<?php
// Вывод текстовой строки в окно браузера
echo "Hello world!";
?>

и после точки с запятой

<?php
echo "Hello world!"; // Вывод текстовой строки в окно браузера
?>

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

<?php
if($tot)
{
while($position = next($tot))
{
/* Очень длинный код
содержащий много
вложенных блоков
...
*/
if($flag)
{
echo "Ошибка";
exit();
} } // Конец while($position = next($tot))
}
?>
Имена переменных и функций
Существует несколько стилей названия переменных
$var_bell — стиль C: нижний регистр, знак подчёркивания.

$VarBell — стиль Pascal: каждая подстрока в названии начинается с большой буквы.
$varBell — стиль Java: первая строка начинается с маленькой буквы, все последующие с большой.
Не имеет значения, какой стиль будет вами выбран — главное придерживаться в коде одного стиля.

Замечание
В программировании константы традиционно записываются в верхнем регистре YANDEX_BOT. Если вы хотите, чтобы другие программисты могли легко воспринимать ваш код, придерживайтесь этого правила.

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

Рассмотрим несколько примеров. Часто временные строки для хранения SQL называют $query (запрос) — это очень удачное название, ассоциирующееся именно с SQL-запросом. Обычно на этом всё и заканчивается. При появлении второго запроса, вторая переменная получает имя $query1 — это порочная практика. Обычно запросы в рамках одного скрипта отличаются своим действием: один SQL-запрос может выполнять обновление (UPDATE), другой выборку (SELECT), поэтому переменные лучше называть с указанием действия оператора: $query_update и $query_select, соответственно.

Часто можно увидеть код

<?php
$query = "SELECT * FROM catalog";
$query1 = mysql_query($query);
while($result = mysql_fetch_array($query1))
{
/* Код обработки */
}
?>
Здесь дескриптор запроса, возвращаемый функцией mysql_query() назван $query1, это здорово запутывает как разработчика, так и читающего текст программы. Дескриптор не несёт физического смысла — это лишь ключ к результату, поэтому его лучше называть сокращённым именем таблицы

<?php
$query = "SELECT * FROM catalog";
$cat = mysql_query($query);
while($catalog = mysql_fetch_array($cat))
{
/* Код обработки */
}
?>