我應該採用哪種模式來評論我的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's表示法已經達到了PHP行業標準的地位。他們的tutorial給出了它如何工作的一個很好的概要。 Here是一個帶有phpDoc樣式註釋的完整示例PHP文件。總之，文檔標準是每一個文件，類和方法與前面「文檔塊」：

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

我真的很喜歡在任何函數標題或類標題註釋周圍留下/* ... */評論。

內嵌代碼評論的//很容易，但#評論也很容易。在我的編輯器中，他們根據我使用的評論類型顯示了各種顏色（jEdit），我使用這種方式來獲得優勢。

此外，只是對的樣式您的評論...我強烈建議使功能標題註釋更具描述性。例如，函數頭應該告訴你你在代碼中做了無效的jpeg檢查，而不是不得不讀下去，發現無效的jpeg會引發錯誤 - 應該在註釋頭塊中說。

Answer 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？這是不言自明的，不需要評論。

當然，您可能需要爲函數添加註釋以自動生成文檔，這很好。但只有在真正有必要的地方使用註釋並嘗試寫出富有表現力的代碼。

---

順便說一句另一種寫評論的方式是/*...*/。

Answer 4

縮進確實不錯了相當數量的：

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

我會看看PhpDocumenter這是創建你的代碼的HTML文檔的工具。

這裏是如何記錄你的代碼是初學者教程：

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

Answer 6

你會想在這樣的方式評論是多餘的代碼。

我會重構此代碼以減少評論的需求。我會創建新的方法，如isJpeg（），我會從函數中刪除重定向，而使用像redirectUnless（valid_image（））之類的東西。

類似下面的聲明不需要任何評論，因爲任何人都可以理解它的作用。

if ($image->isJpeg()) 

我還會推薦閱讀Clean Code。

Answer 7

一件大事就是保持您的評論簡潔。例如：

---

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

...應該沒有必要。他們會讓難以跟蹤有用的評論和代碼本身。代碼相關的塊之間

換行符也可以幫助澄清了很多東西。