Question

在过去的两个月里，我一直在学习PHP，我发现有两种以上的样式用来评论代码！我没有看到很多一致性......我认为这通常意味着工作中的艺术家。所以我想知道：评论的有效方法是什么仍然可读/实用？并排查看1个地方的所有有效可能性将提供我希望改进评论的概述

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

Answer 1

引用评论手册：

PHP支持'C'，'C ++'和Unix shell风格（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
?>

一般情况下，您需要avoid using comments in your sourcecode。引用Martin Fowler的话：

当您觉得需要撰写评论时，首先尝试重构代码，以便任何评论都变得多余。

这意味着类似

// 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) { …

我认为如果剩下的方法签名清楚地传达了它的作用，你可以省略短篇和长篇。但是，这需要一定的纪律和知识，如何实际写Clean Code。例如，以下内容完全是多余的：

/**
 * 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文档。重要的是，无论你决定做什么，都要坚持不懈。

Answer 2

你绝对应该使用phpdoc标准。这是初学者的quick start。

我确定你看过这样的评论：

/**
 * 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开发人员不仅可以轻松阅读，而且还可以生成精美的文档。

Answer 3

对我来说，每个人看起来都同样可读我也使用单行和多行注释。

以灰色突出显示，它们始终可见并且与其他代码不同。
我在

之前看过没有关于评论可读性的单一问题

Answer 4

使用phpdoc guidelines进行评论是很常见的。这包括用于生成文档的注释。

什么是有效＆amp;在PHP5中评论的可读方法？

4 个答案: