我应该采用哪种模式来评论我的PHP代码?

考虑用注释代码 文档 记住:程序文档可以从源代码注释自动生成,这非常有用,迟早会成为一个问题。

我想可以这么说 phpDocumentor's 符号已达到PHP行业标准的状态。他们 tutorial 详细介绍了它的工作原理。 Here 是包含phpDoc样式注释的完整的PHP示例文件。简而言之,文档标准是在每个文件、类和方法前面加上“docblocks”:

/**  
 * This is a description of my function
 * @param string this is a description of the first parameter
 * @param int this is a description of the second parameter
 * @return int this describes what the function returns
 */ 

 function myfunc ($param1, $param2)
  { ...  }

phpdocumentor有许多预定义的 @keyword 关键词: @license , @version , @deprecated 还有很多,更多。

许多phpide都认识到这种表示法,并且能够从中提取您键入时出现的查找信息。

许多IDE用来编译任务列表的关键字是 @todo .

phpdoc和consorts没有设置规则的一个领域是“内联注释”,就像在特定步骤之间的注释一样。

据我所知,这里没有有约束力的规则;然而,多年来,特别是自从我加入以来,我越来越不热衷于评论我的代码所做的每一步,采用 “好的代码应该注释自己” .

这意味着限制对代码中尚不明显的内容的注释,以及所用变量的名称。(变量名中的好选择是 极其 重要,比冗长的评论更重要!)

这并不完全回答你的问题,但只包括解释 为什么 你在做某种事情。通过使用有意义的变量和函数名,您的代码应该是不言而喻的。

让我们看看

//Check if the uploaded image is of type jpeg
//if not then pop up a warning message and return false and redirect back
if( $image["type"] !== "image/jpeg") {
    alert('File must be of type image/jpeg'); 
    redirect_url($url);           
    return false;
}

你甚至不需要在这里评论。很明显,您检查图像的类型,然后显示某种类型的错误消息。 image , type , jpeg , redirect 和 return false 甚至出现在代码中。

这样,您可以删除不必要的注释,代码看起来会更好。

还要考虑更改函数名 valid_image 没有表现力。您的注释解释了函数检查图像是否有效。为什么不命名函数 isImageValid ?这是不言自明的,不需要评论。

当然,您可能希望向函数添加注释以自动生成文档,这很好。但只在真正必要的地方使用注释,并尝试编写表达性代码。

另外一种写评论的方法是 /*...*/ .

重要的是保持你的评论简洁。例如:

//If the function has got all the parameter then check both the defined height and width 
//Print the appropriate message and return false and redirect back

可以是:

//IF ALL PARAMS ARE PRESENT, VERIFY DIMENSIONS

//Check if the uploaded image is of type jpeg
//if not then pop up a warning message and return false and redirect back

可以是:

//JPEG IMG?

也不要评论一些不言自明的东西。评论如下:

//if not then pop up a warning message and return false and redirect back

…不应该是必要的。它们将使跟踪有用的注释和代码本身变得更加困难。

相关代码块之间的换行符也可以帮助澄清很多事情。

您将希望以这样一种方式编码,即注释是多余的。

我将重构此代码以减少对注释的需要。我将创建新的方法,如isjpeg(),并从函数中删除重定向,而是使用类似redirectUntil(valid_image())的方法。

像下面这样的声明不需要注释,因为任何人都可以理解它的作用。

if ($image->isJpeg())

我进一步推荐阅读 Clean Code .

将其缩进可产生相当数量的好处:

//function to check if the uploaded Image is valid
function valid_image($image, $target, $url, $width, $height = 0) {
    //Check if the uploaded image is of type jpeg
    //if not then pop up a warning message and return false and redirect back
    if( $image["type"] !== "image/jpeg") {
        alert('File must be of type image/jpeg'); 
        redirect_url($url);           
        return false;
    }
    //Check the file Dimension of the Uploaded Image if it matches with the defined Value
    //Get the Dimensions of the image
    list($image_width, $image_height) = getimagesize($image['tmp_name']);
    //If the Parameter Height is empty then just check the image width and ignore the height rule
    //Print the appropriate message and return false and redirect back
    if( $height == '0' && $image_width !== $width) {
        alert("Incorrect File Dimension for  " . $image['name'] . " Please make sure it is $width in width");
        redirect_url($url);
        return false;
    }
    //If the function has got all the parameter then check both the defined height and width 
    //Print the appropriate message and return false and redirect back
    else if($image_width !== $width || $image_height !== $height) {
        alert("Incorrect File Dimension for  " . $image['name'] . " Please make sure it is  $width X $height  ");
        redirect_url($url);
        return false;
    }
    return true;
}

我想看看 PhpDocumenter 这是一个创建代码HTML文档的工具。

以下是关于如何记录代码的初学者教程:

http://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#basics.starting

我真的很喜欢 /* ... */ 围绕任何函数头或类头注释的注释。

的内联代码注释 // 很容易,但也很容易 # 评论。在我的编辑器中,根据我使用的注释类型(jedit),它们显示为各种颜色,这对我有利。

而且,简单地说 你的 评论。。。我强烈建议让函数头注释更具描述性。例如,函数头应该告诉您在代码中所做的无效jpeg检查,而不是必须向下读取并发现无效的jpeg将抛出一个错误——它应该在注释头块中这样说。