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

文件注釋

/*** 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 <something@email.com>* @version 1.0* @package PHP_CodeSniffer*/ 復制代碼

簡介或名稱。

當前使用PHP版本。

當前文件的詳細介紹。

@author 作者，語法：@author name <email>。此標記可以用來標記任何可以記錄的元素（包括但不限于全局變量，變量，引入，常量，方法，類，頁面等）。

@version 版本，語法：@version ["Semantic Version"] [description]。同樣可以記錄所有元素的版本。

@package 包，語法：@package [level 1]\[level 2]\[etc.]。用于將相關的頁面或類進行邏輯分組。

類注釋

/*** Sample class comment** @category PHP* @package PHP_CodeSniffer* @author Greg Sherwood <something@email.com>* @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 復制代碼

簡介或名稱。

@category 分類，該標記用于將多個包package組合在一起。

@package 包，用于邏輯分組。

@author 作者,語法：@author name <email>。

@license 許可證，語法：@license [<SPDX identifier>|URI] [name],該標記向用戶提供許可信息，第一個參數是由SPDX開源許可證注冊機構定義的“SPDX標識符” ，或者是包含完整許可證文本的文檔的URL.第二個參數可以是適用許可證的正式名稱，文中的BSD Licence是開源界的五大許可協議之一。在寫開源項目的時候選擇一個適合的開源License尤為重要，許可的目的是，向使用你產品的人提供一定的權限。

@link 鏈接,語法：@link [URI] [description],標記指示關聯的“結構元素”和網站之間的自定義關系，該關系由絕對URI標識。他也可以用于鏈接到其它方法，例：@link MyClass,不過一般來說，如果您想鏈接到元素的文檔，請使用@see或inline {@link}可能會是一個更好的選擇。

方法注釋

/*** Return a thingie based on $paramie* @param boolean $paramie * @return integer|babyclass*/ function parentfunc($paramie) {if ($paramie) {return 6;} else {return new babyclass;} } 復制代碼

簡介或名稱。

@param 參數,語法：@param ["Type"] [name] [<description>],標簽用于記錄函數或方法的單個參數,且可以有多行描述，不需要明確的分隔。

@return 返回，語法：@return <"Type"> [description],標簽用于記錄函數或方法的返回類型，同樣支持多行描述。

變量注釋

/*** Configuration values* @var array $thirdvar*/ var $thirdvar; 復制代碼

變量描述。

@var 變量，語法:@var ["Type"] [element_name] [<description>]，標簽用于記錄變量類型，也用于記錄常量等

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

后記

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

好的注釋也是讓別人了解你代碼思想的一部分，向寫注釋的程序員致敬！(￣^￣)ゞ

共勉~

《新程序員》：云原生和全面數字化實踐50位技術專家共同創作，文字、視頻、音頻交互閱讀

總結

以上是生活随笔為你收集整理的PHP中类和文件的代码注释规范的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。