За последние 2 месяца, что я изучал PHP, я определил более двух стилей, которые люди используют для комментариев кода! Я не видел много консистенции … что, я думаю, обычно означает, что художники на работе . Поэтому я задавался вопросом: каковы допустимые способы комментариев, которые по-прежнему доступны для чтения / практического? Увидев все допустимые возможности в одном месте рядом, вы получите обзор, который я ищу, чтобы улучшить комментирование
/* | This is what I now use (5chars/3lines) I name it star*wars \* Цитирование Руководства по комментариям:
PHP поддерживает комментарии «C», «C ++» и Unix shell-style (Perl style). Например:
<?php echo 'This is a test'; // This is a one-line c++ style comment /* This is a multi line comment yet another line of comment */ echo 'This is yet another test'; echo 'One Final Test'; # This is a one-line shell-style comment ?>
В общем, вы захотите избежать использования комментариев в исходном коде . Процитировать Мартина Фаулера:
Когда вы чувствуете необходимость писать комментарий, сначала попробуйте реорганизовать код, чтобы любые комментарии стали излишними.
что означает что-то вроде
// check if date is in Summer period if ($date->after(DATE::SUMMER_START) && $date->before(DATE::SUMMER_END)) {
следует переписать на
if ($date->isInSummerPeriod()) { …
Другой тип комментария, с которым вы иногда сталкиваетесь, – это комментарий разделителя, например, что-то вроде
// --------------------------------------------
или
################################################
Обычно это указывает на то, что код, в котором они используются, делает слишком много. Если вы найдете это в классе, проверьте ответственность класса и посмотрите, лучше ли его часть реорганизуется в отдельный класс.
Что касается документов API, то общая нотация – PHPDoc , например
/** * Short Desc * * Long Desc * * @param type $name description * @return type description */ public function methodName($name) { …
Я бы сказал, что вы можете опустить Short и Long Desc, если остальная сигнатура метода четко сообщает, что она делает. Однако для этого требуется определенная дисциплина и знания о том, как писать чистый код . Например, следующее совершенно излишне:
/** * Get the timestamp property * * The method returns the {@link $timestamp} property as an integer. * * @return integer the timestamp */ public function getTimestamp() { …
и следует сократить до
/** * @return integer */ public function getTimestamp() { …
Излишне говорить, что вы идете за полным API-документами или нет, также зависит от проекта. Я бы ожидал, что любая фреймворк, который я смогу загрузить и использовать, будет иметь полные API-документы. Важно то, что все, что вы решите делать, делать это последовательно.
Вы должны обязательно использовать стандарты phpdoc. Вот быстрый старт для начинающих.
Я уверен, что вы видели такие комментарии:
/** * example of basic @param usage * @param bool $baz * @return mixed */ function function1($baz) { if ($baz) { $a = 5; } else { $a = array(1,4); } return $a; }
Комментирование этого пути делает его не только простым для большинства PHP-разработчиков, но и вы можете создавать хорошие документы.
Для меня каждый из них выглядит одинаково читаемым.
Я использую как однострочные, так и многострочные комментарии.
Будучи выделены серым цветом, они всегда видны и отличаются от другого кода.
Я не видел ни одной проблемы с читабельностью комментариев до
Для комментирования довольно часто используется руководство phpdoc. Сюда входят аннотации для создания документации.