Профессиональное программирование на PHP

Страница 40 из 591


42 Глава 1 Стили кодирования

Внутренние комментарии

РНР поддерживает три вида синтаксиса для внутренних комментариев кода.

 Комментарии в стиле С - весь текст между символами /* и */ является комментарием. Пример С-стиля комментариев:

/* Комментарий в стиле С

* (продолжение комментария) */

 Комментарии в стиле С++ - весь текст в строке, следующий за символами //, является комментарием. Пример комментария в С++-стиле:

// Комментарий в стиле С++

 Комментарии в стиле Shell/Perl - разделителем является символ фунта (#). Пример комментария в стиле Shell/Perl:

# Комментарий в стиле shell

Рекомендуется избегать ShelI/Perl-стиля комментариев. Для крупных блоков комментариев следует использовать С-стиль, а С++-стиль наилучшим образом применим для однострочных комментариев.

Комментарии необходимо применять для пояснения кода. Ниже приводится классический пример бесполезного комментария:

// increment i

i + +;

Комментарий просто называет то, что делает оператор (а это и так очевидно любому, кто умеет читать код), и не поясняет, почему используется данная операция. Бессодержательные комментарии только загромождают код.

Ниже приведен пример полезного комментария:

// Чтобы определить четность $i,

// используется поразрядный оператор "AND", который проверяет, // установлен ли в $i первый бит if($i & 1) { return true;

} .

Комментарий поясняет, что выполняется проверка того, установлен ли первый бит, поскольку в этом случае число является нечетным.

API-документация

Документирование API-интерфейса для внешних пользователей отличается от внутреннего документирования кода. Цель API-документации заключается в том, чтобы гарантировать, что разработчикам для того, чтобы понять, как использовать данный код, вообще не придется его просматривать. API-документация существенна для PHP-библиотек, которые поставляются как часть продукта, а также чрезвычайно полезна для документирования библиотек, которые являются внутренними для коллектива разработчиков.



  • Раздвижные межкомнатные двери и системы дверей с установкой.

  Hostland.Ru

 «Бесплатный хостинг Hostland.Su» © 2006