Каковы правильные и читабельные подходы к комментированию в PHP5? - PullRequest
Новая
       28

Каковы правильные и читабельные подходы к комментированию в PHP5?

8 голосов
/ 11 апреля 2011

За последние 2 месяца, которые я изучал PHP, я определил более двух стилей, которые люди используют для комментирования кода!Я не видел большой последовательности ... что, как мне кажется, обычно означает художников на работе .Поэтому я задался вопросом: каковы действительные способы комментирования, которые все еще читаемы / практичны?Просмотр всех действительных возможностей в 1 месте рядом предоставит обзор, который я ищу для улучшения комментариев 

/*
|  This is what I now use (5chars/3lines) I name it star*wars
\*

Ответы [ 4 ]

9 голосов
/ 11 апреля 2011

Цитирование руководства по комментариям:

PHP поддерживает комментарии 'C', 'C ++' и Unix в стиле оболочки (стиль Perl). Например: 

<?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. Важно только то, что, что бы вы ни решили делать, делайте это последовательно.

3 голосов
/ 11 апреля 2011

Вы обязательно должны использовать стандарты 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-разработчики для чтения, но вы также можете создавать хорошие документации.

2 голосов
/ 11 апреля 2011

Мне каждый из них выглядит одинаково читаемым.
Я использую как однострочные, так и многострочные комментарии.

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

1 голос
/ 11 апреля 2011

Для комментариев достаточно часто использовать phpdoc Guidelines .Сюда входят аннотации для создания документации.

...