logo标签列表

我应该采用哪种模式来注释我的PHP代码？

php
4
我刚刚完成了我的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;
            }

Thanks in Advance.

7
代码注释模式1：正确缩进代码。 - Eric
7个回答
11
考虑以文档为中心对代码进行注释：程序文档可以从源代码注释中自动生成，这非常有用，并且迟早会成为一个问题。
我认为可以毫不夸张地说，phpDocumentor 的标记已经达到了 PHP 行业标准的地位。他们的教程很好地介绍了它的工作原理。这里是一个带有 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和其它工具没有规定“内联注释”的规则，例如您在特定步骤之间使用的注释。

据我所知，这里没有任何约束规则。然而，多年来，尤其是自从我加入SO以来，我越来越不热衷于注释我的代码每一步，采用了一个哲学：“好的代码应该自我注释”。

这意味着限制对那些从代码和变量名称中已经显而易见的事情进行注释。（在变量名称方面做出良好选择非常重要，比冗长的注释更重要！）

+1 很棒的答案。涵盖了所有方面：开发人员、文档编写者、集成开发环境。 - webbiedave
1
+1 太棒了。当 phpDoc 运行时，您需要确保 (a) 您的类注释描述了类的单一目的以及它与其他类的关系（除了继承），并且 (b) 您的方法注释足够描述了方法的目标，以便编写单元测试。此外，@package 标签对于组织大型代码库的文档非常重要。 - grossvogel
3

这并不完全回答你的问题，而是仅包含解释为什么以某种方式执行操作的注释。您的代码应该使用有意义的变量和函数名称来自我说明。

让我们看一下

//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？这是不言自明的，不需要注释。
当然，你可能想在函数中添加注释以生成文档，这也没问题。但只有在真正需要时才使用注释，并尽量编写表达力强的代码。
顺便说一下，写注释的另一种方式是/*...*/。
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

不应该必须使用注释。它们会使有用的注释和代码本身更难以跟踪。

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

1
你需要以一种无需注释的方式编程。
我会重构这段代码以减少注释的需要。我会创建新的方法，例如isJpeg()，并将重定向从函数中移除，而是使用类似于redirectUnless(valid_image())的东西。
像以下这样的语句不需要注释，因为任何人都能理解它的作用。
if ($image->isJpeg())

我进一步推荐阅读《代码整洁之道》。
0

缩进可以起到相当不错的作用：

//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;
}
对不起，什么是缩进？ - Ibrahim Azhar Armar
@Ibrahim Azhar Armar：就像函数内的所有代码都“向右缩进”一样，缩进了四个空格。这就是缩进，使哪些块属于一起更清晰。如有必要，请查阅适当的字典。 - Felix Kling
0

我非常希望在任何函数头或类头注释周围有/* ... */注释。

//的内联代码注释很容易，但#注释也很容易。在我的编辑器中，它们根据我使用的注释类型显示为不同的颜色（jEdit），我利用这一点。

此外，就你的注释风格而言...我强烈建议使函数头注释更加描述性。例如，函数头应该告诉您有关代码内部正在进行的无效jpeg检查，而不是必须向下阅读并发现无效的jpeg将引发错误-它应该在注释头块中说明。

0
网页内容由stack overflow 提供, 点击上面的
可以查看英文原文，
原文链接