PHP中類和文件的代碼註釋規範

NO IMAGE

編寫好的文檔對於任何軟件項目都至關重要,不僅是因為文檔的質量可能比代碼的質量更重要,還因為良好的第一印象會促使開發人員進一步查看代碼以及後續的迭代。

文件註釋

/**
* Sample file comment
*
* PHP version 7.1.0
* 
* This file demonstrates the rich information that can be included in
* in-code documentation through DocBlocks and tags.
* @author Greg Sherwood <[email protected]>
* @version 1.0
* @package PHP_CodeSniffer
*/
  1. 簡介或名稱。
  2. 當前使用PHP版本。
  3. 當前文件的詳細介紹。
  4. @author 作者,語法:@author name <email>。此標記可以用來標記任何可以記錄的元素(包括但不限於全局變量,變量,引入,常量,方法,類,頁面等)。
  5. @version 版本,語法:@version ["Semantic Version"] [description]。同樣可以記錄所有元素的版本。
  6. @package 包,語法:@package [level 1]\[level 2]\[etc.]。用於將相關的頁面或類進行邏輯分組。

類註釋

/**
* Sample class comment
*
* @category  PHP
* @package   PHP_CodeSniffer
* @author    Greg Sherwood <[email protected]>
* @license   https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
* @link      http://pear.php.net/package/PHP_CodeSniffer
*/
class Missing_Newlines_Before_Tags
{
}//end class
  1. 簡介或名稱。
  2. @category 分類,該標記用於將多個包package組合在一起。
  3. @package 包,用於邏輯分組。
  4. @author 作者,語法:@author name <email>
  5. @license 許可證,語法:@license [<SPDX identifier>|URI] [name],該標記向用戶提供許可信息,第一個參數是由SPDX開源許可證註冊機構定義的“SPDX標識符” ,或者是包含完整許可證文本的文檔的URL.第二個參數可以是適用許可證的正式名稱,文中的BSD Licence是開源界的五大許可協議之一。在寫開源項目的時候選擇一個適合的開源License尤為重要,許可的目的是,向使用你產品的人提供一定的權限。
  6. @link 鏈接,語法:@link [URI] [description],標記指示關聯的“結構元素”和網站之間的自定義關係,該關係由絕對URI標識。他也可以用於鏈接到其它方法,例:@link MyClass,不過一般來說,如果您想鏈接到元素的文檔,請使用@seeinline {@link}可能會是一個更好的選擇。

方法註釋

/**
* Return a thingie based on $paramie
* @param boolean $paramie 
* @return integer|babyclass
*/
function parentfunc($paramie)
{
if ($paramie) {
return 6;
} else {
return new babyclass;
}
}
  1. 簡介或名稱。
  2. @param 參數,語法:@param ["Type"] [name] [<description>],標籤用於記錄函數或方法的單個參數,且可以有多行描述,不需要明確的分隔。
  3. @return 返回,語法:@return <"Type"> [description],標籤用於記錄函數或方法的返回類型,同樣支持多行描述。

變量註釋

/**
* Configuration values
* @var array $thirdvar
*/
var $thirdvar;
  1. 變量描述。
  2. @var 變量,語法:@var ["Type"] [element_name] [<description>],標籤用於記錄變量類型,也用於記錄常量等

值得說明的是,@category@link這兩個標記在新發布的PSR-5PHP文檔標準中被標註為已廢棄[deprecated],可正常使用,但不推薦使用,文檔能正常生成。

後記

這樣寫出來生成的代碼註釋,也方便後期維護,而且PSR-5出了關於代碼文檔的規範,通過使用phpDocumentor還能生成自己的軟件項目文檔,他還提供生成不同受眾顯示不同文檔內容,很是方便,上面的模板只是簡單的介紹幾個場景下經常用到的Tag,實際情況請選擇使用適合的標籤,形成自己項目的代碼註釋規範。更多可查看官方的介紹

好的註釋也是讓別人瞭解你代碼思想的一部分,向寫註釋的程序員致敬!( ̄^ ̄)ゞ

共勉~

相關文章

概述javascript部分核心機制

nodejs微服務框架解決方案

淺析網絡應用中常用的加密手段

為什麼Julia這麼快?