Question

我刚刚完成编码我的PHP应用程序现在编码已经变得有些巨大而且我正在使用的评论看起来很丑陋和无效，因为我评论的每一行代码都是//，这是我的第一个编码和我我完全没有意识到采用的方法，使我的评论看起来更好，更清洁，以便将来参考我或任何人。如果有人用例子向我推荐这个模式，我将不胜感激。

这是我用我用过的丑陋评论写的函数。你会用哪种模式来评论代码？

//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') {
        if( $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;
            }

先谢谢。

Answer 1

考虑使用文档评论您的代码：可以从源代码注释中自动生成程序文档，这非常有用，迟早会成为问题。

我认为可以说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以及许多其他关键字。

许多PHP IDE都能识别这种表示法，并能够从键盘中提取查找信息。

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

phpDoc和consorts没有设置规则的一个领域是“内联注释”，就像你在特定步骤之间所拥有的那样。

据我所知，这里没有约束规则;然而，多年来，尤其是在我加入SO之后，我对评论我的代码所做的每一步都变得越来越不热心，采用“优秀代码应该评论自己”的理念

这意味着限制对代码中尚未显而易见的事物的评论，以及所使用的变量的名称。（变量名称中的好选择非常重要，比详细评论更重要！）

Answer 2

这并不完全回答您的问题，但只包含解释为什么以某种方式做某事的评论。通过使用有意义的变量和函数名，您的代码应该是不言自明的。

让我们来看看

//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？这是不言自明的，不需要评论。

当然，您可能需要在函数中添加注释以自动生成文档，这很好。但只能在真正需要的地方使用注释，并尝试编写富有表现力的代码。

顺便说一下写评论的另一种方式是/*...*/。

Answer 3

重要的是让你的评论简明扼要。例如：

//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

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

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

Answer 4

您需要以评论多余的方式进行编码。

我会重构此代码以减少评论的需要。我会创建新的方法，比如isJpeg（），我会从函数中删除重定向，而是使用像redirectUnless（valid_image（））这样的东西。

如下所示的声明不需要任何评论，因为任何人都可以理解它的作用。

if ($image->isJpeg())

我还建议您阅读Clean Code。

Answer 5

我真的更喜欢围绕任何函数标头或类标题注释发出/* ... */条评论。

//的内联代码注释很简单，#注释也是如此。在我的编辑器中，它们根据我使用的评论类型显示各种颜色（jEdit）我使用这个对我有利。

另外，关于你的评论的风格......我强烈建议让函数标题评论更具描述性。例如，函数头应该告诉您在代码中执行的无效jpeg检查，而不是必须读取并发现无效的jpeg将引发错误 - 应该在注释头块中说明。

Answer 6

缩进它确实有很多好处：

//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;
}

Answer 7

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

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

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

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

7 个答案: