如何在程序代码中更高效地使用 DocBlock 注释？答案

【问题标题】：How to use DocBlock comments in procedural code more effecient?如何在程序代码中更高效地使用 DocBlock 注释？
【发布时间】：2014-04-13 18:30:02
【问题描述】：

我正在编写程序 PHP 风格的脚本，但仍想尽我所能记录所有内容。这就是我使用 DocBlock cmets 的原因。作为新手，我想知道如何在以下场景中使用它们（专门为此问题编写的代码）：

/**
 * Checks string length
 *
 * @param int $max_length  an integer determining the string length to check against
 * @param string $string  the string to be checked
 * @return bool  a boolean value indicating if the string is shorter or longer
 *               than $max_length. True if shorter, false if longer
 */
function check_length( $max_length = 2, $string ) {
    $i = 0;

    if( strlen( $string ) > $max_length )
        return false;

    return true;
}

假设该功能需要$i。我应该如何记录它？我不能把它放在函数 DocBlock 中，因为它不是参数。

example 在该类中有两个相似的变量，但由于我没有编写面向对象的代码，我不能将 $i 放在函数之外（或者只是不想将我的编码风格更改为能够使用 DocBlocks）。

另一种方法是不记录这些“内部”变量，因为对于使用该函数，它们并不重要。

【问题讨论】：

我看不出你的 $i 变量的意义。不管怎样，如果$i 很重要，或者诸如此类，我要么在文档块中（在标题下）包含一个简短的解释，要么在一个内联注释中解释$i 的用途。此外，您必须在可选参数之前有必需的参数。在您的示例中，$max_length = 2 之后不能有 $string。它们应该以相反的方式放置，或者给 $string 一个默认值。

标签： php comments docblocks

【解决方案1】：

PHP-Doc-Comments 可以被视为您的模块/类/任何东西的 API 文档。由于 $i 对您的代码的用户不感兴趣 - 为什么要将它放入您的 API 文档中？您的用户不需要知道它，因此您不应该告诉他们。 $i 可能对实际阅读或审查您的代码的人很感兴趣。因此，您应该添加一个简单的单行注释 (//) 来描述 $i 是/做什么，或者如果需要，添加一个多行注释。

【讨论】：