在做網(wǎng)站中,不寫(xiě)不必要的注釋?zhuān)挥挟敶a不能很好地說(shuō)明邏輯時(shí),才用注釋補充;把注釋看成程序的一部分,在編寫(xiě)/維護代碼時(shí)同時(shí)編寫(xiě)/維護注釋?zhuān)蛔⑨屚耆捎肞HPDocumentor的規范,以方便用其生成API級文檔。下面給出各個(gè)部分的注釋示范。
1. 文件頭注釋注釋包括以下方面。
(1)項目、模塊名稱(chēng),文件名稱(chēng)、功能說(shuō)明。
(2)模塊或文件的使用說(shuō)明。
(3)作者、日期。
(4)修改記錄。
示范:
<?php/***************************************** 項目名稱(chēng):ZMedia 數據抓取服務(wù)* 文件名稱(chēng):ZMedia-Spider.php* 文件功能:服務(wù)運行入口****************************************** 運行方式:php ./ZMedia-Spider.php [-s] [控制信號] [-d]* 參數說(shuō)明:* -s 控制信號:start(開(kāi)始運行)、stop(結束運行)、restart(重新啟動(dòng))* -d 調試狀態(tài),終端窗口顯示輸出調試信號,否則無(wú)窗口運行輸出到日志** 如:php ./ZMedia-Spider.php -s restart -d debug******************************************* 創(chuàng )建日期:2015-05-01* 創(chuàng )建作者:張三****************************************** 修改記錄:* 2015-05-01,V1.0,創(chuàng )建文件****************************************/
2. 類(lèi)注釋
注釋包括以下方面。
(1)類(lèi)名稱(chēng)。
(2)作者、日期。
(3)修改記錄。
示范:
<?php/****************************************** 文件功能:日志記錄類(lèi)****************************************** 創(chuàng )建日期:2015-05-21* 創(chuàng )建作者:張三****************************************** 修改記錄:* 2015-05-21,V1.0,創(chuàng )建文件****************************************/
3. 函數/類(lèi)方法注釋
注釋包括以下方面。
(1)函數/類(lèi)方法的功能說(shuō)明。
(2)輸入參數說(shuō)明。
(3)輸出結果說(shuō)明。
(4)(可選)實(shí)現流程說(shuō)明。
示范:/************************************************************ 功能:PHP截取UTF-8字符串,解決半字符問(wèn)題。* 說(shuō)明:英文、數字(半角)為1字節(8位),中文(全角)為3字節************************************************************* 輸入:$str 源字符串* $len 左邊的子串的長(cháng)度* 輸出:取出的字符串,當$len小于等于0時(shí),會(huì )返回整個(gè)字符串************************************************************/function utf-substr($str, $len)
當前文章標題:注釋規范
當前URL:http://amzcoolest.com/news/wzzz/3252.html
上一篇:PHP編碼規范
下一篇:表單結構