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

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的符号已达到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和consorts没有设置规则的一个领域是"内联注释",就像你在特定步骤之间所拥有的那样.

据我所知,这里没有约束规则; 然而,多年来,特别是自从我加入SO之后,我对评论我的代码所做的每一步都变得越来越不热心,采用了"良好代码应该评论自己"的理念.

这意味着限制对代码中未显而易见的事物的评论,以及所使用的变量的名称.(变量名的好选择非常重要,比冗长的评论更重要!)