使用一致的模擬群來進(jìn)行類和方法，以增強(qiáng)IDE支持，澄清目的和輔助靜態(tài)分析。 2。使用@return的文檔返回類型，以指定PHP本機(jī)類型無法表達(dá)的數(shù)組結(jié)構(gòu)。 3。 @param中具有約束和格式的註釋參數(shù)，以明確要求隱式要求。 4.在代碼更改期間保持評(píng)論更新，並將其視為審查過程的一部分，以防止錯(cuò)誤信息。 5。使用@throws，@deprecated，@see和@var等戰(zhàn)略標(biāo)籤來改善錯(cuò)誤處理，折舊管理和交叉引用，以確保代碼庫(kù)中的長(zhǎng)期可維護(hù)性和清晰的通信。

編寫可維護(hù)的代碼不僅涉及乾淨(jìng)的邏輯和良好的體系結(jié)構(gòu)，還與清晰的交流有關(guān)。在PHP項(xiàng)目中，尤其是由團(tuán)隊(duì)或長(zhǎng)時(shí)間內(nèi)維護(hù)的項(xiàng)目中，結(jié)構(gòu)化的塊評(píng)論是提高可讀性，支持IDE並使重構(gòu)更安全的簡(jiǎn)單但功能強(qiáng)大的工具。

儘管PHP具有現(xiàn)代功能，例如類型的提示和屬性，但具有一致塊註釋的有據(jù)可查的代碼仍然是必不可少的，尤其是對(duì)於不可行的完整類型覆蓋範(fàn)圍的複雜方法，類或舊類型的系統(tǒng)。

這是如何有效地使用結(jié)構(gòu)化的PHP塊評(píng)論來構(gòu)建更可維護(hù)的代碼庫(kù)。

1。始終將DocBlocks用於類和方法

DocBlock是標(biāo)準(zhǔn)化的評(píng)論格式，上面放置了類，方法，屬性和功能。它使用IDE識(shí)別的特定結(jié)構(gòu)，文檔生成器（例如phpdocumentor）和靜態(tài)分析儀。

 /**
 *管理用戶身份驗(yàn)證和會(huì)話生命週期。
 *
 *此類處理登錄，註銷和令牌驗(yàn)證。
 *它與用戶和令牌存儲(chǔ)庫(kù)集成。
 *
 * @package應(yīng)用\ auth
 * @author jane doe <jane@example.com>
 * @license麻省理工學(xué)院
 * @link https://example.com/docs/auth
 */
班級(jí)Authmanager
{
    /**
     *嘗試通過電子郵件和密碼對(duì)用戶進(jìn)行身份驗(yàn)證。
     *
     * @param字符串$電子郵件用戶的電子郵件地址
     * @param字符串$密碼plain-text密碼（外部驗(yàn)證）
     * @return數(shù)組{用戶：用戶| null，成功：布爾，消息：字符串}
     *
     * @throws AuthenticationException如果帳戶已鎖定或禁用
     */
    公共功能登錄（字符串$電子郵件，字符串$密碼）：數(shù)組
    {
        // ...
    }
}

為什麼會(huì)有所幫助：

• IDE使用此顯示工具提示，自動(dòng)完成參數(shù)並檢測(cè)類型不匹配。
• 未來的開發(fā)人員（或您在6個(gè)月內(nèi)）立即了解目的和行為。
• 當(dāng)實(shí)際類型丟失時(shí)，Phpstan或Psalm等靜態(tài)分析工具依賴於這些提示。

2.文檔返回類型 - 尤其是複雜的類型

PHP的本地返回類型很棒，但是它們無法表達(dá)所有內(nèi)容 - 例如具有特定形狀或混合關(guān)聯(lián)結(jié)構(gòu)的陣列。

使用@return澄清：

 /**
 *從數(shù)據(jù)庫(kù)中獲取了分頁的結(jié)果。
 *
 * @param int $頁面當(dāng)前頁碼（1個(gè)索引）
 * @param int $限制每個(gè)頁面的最大項(xiàng)目數(shù)
 * @return陣列{
 *數(shù)據(jù)：數(shù)組<int，array {id：int，name：string}>，
 *總計(jì)：int，
 *頁面：int，
 * last_page：int
 *}
 */
公共功能getPaginedusers（int $ page = 1，int $ limit = 10）：數(shù)組
{
    // ...
}

這種細(xì)節(jié)級(jí)別阻止了誤解，並減少了假設(shè)錯(cuò)誤結(jié)構(gòu)引起的錯(cuò)誤。

？ PRO提示：如果您經(jīng)常返回複雜數(shù)組，請(qǐng)考慮創(chuàng)建DTO（數(shù)據(jù)傳輸對(duì)象），然後進(jìn)行文檔。

3。註釋參數(shù)和邊緣案例

即使使用類型聲明，參數(shù)也可能從簽名中明顯地存在約束。

 /**
 *根據(jù)體重和目的地計(jì)算運(yùn)輸成本。
 *
 * @param float $重量必須是> 0
 * @param字符串$ country ISO 2字母鄉(xiāng)村代碼（例如，“我們”，“ de”）
 * @param bool $ express如果是真的，請(qǐng)申請(qǐng)緊急處理費(fèi)
 * @return float積極成本數(shù)量
 *
 * @throws InvalidArgumentException如果體重≤0或無效的國(guó)家代碼
 */
公共功能計(jì)算（float $重量，字符串$ country，bool $ express = false）：float
{
    // ...
}

包括“必須> 0”或格式要求（例如，ISO代碼）之類的期望將隱式知識(shí)轉(zhuǎn)化為明確的文檔。

4。保持評(píng)論與代碼更改保持一致

評(píng)論最大的風(fēng)險(xiǎn)？他們?nèi)鲋e。

過時(shí)的評(píng)論比沒有評(píng)論更糟糕。為了避免這種情況：

• 將評(píng)論視為代碼審查過程的一部分。
• 更改方法行為，參數(shù)或返回值時(shí)更新它們。
• 考慮使用靜態(tài)分析來驗(yàn)證@param類型與實(shí)際簽名匹配。

一些團(tuán)隊(duì)採(cǎi)用了：

• 沒有與過時(shí)的或缺少公共API的模擬器所接受的合併請(qǐng)求。
• 將諸如php_codesniffer的工具與Squiz.Commenting.FunctionComment執(zhí)行標(biāo)準(zhǔn)。

5。策略性地使用標(biāo)籤

常見的有用標(biāo)籤：

• @param和@return - 對(duì)於清晰度至關(guān)重要
• @throws - 文檔異常，幫助呼叫者處理錯(cuò)誤
• @var - 上述屬性，甚至對(duì)複雜變量的內(nèi)聯(lián)屬性
• @deprecated - 標(biāo)記舊代碼和替換建議
• @see或@link - 參考相關(guān)類，文檔或規(guī)格

例子：

 /**
 * @deprecated使用loginService :: authenticate（）而不是。
 * @seee loginService :: authenticate（）
 */
公共功能oldlogin（）
{
    // ...
}

這有助於團(tuán)隊(duì)安全地淘汰舊代碼。

最後的想法

結(jié)構(gòu)化的塊評(píng)論不是寫更多的文章，而是關(guān)於清楚地交流意圖的。當(dāng)持續(xù)使用時(shí)，它們將您的代碼庫(kù)變成一個(gè)自我記錄的系統(tǒng)，該系統(tǒng)更容易導(dǎo)航，調(diào)試和進(jìn)化。

您不需要每行評(píng)論。但是，對(duì)於公共方法，複雜的邏輯或以後可能被重複使用或修改的任何東西，精心製作的圖片塊為自己付費(fèi)很多次。

基本上：首先為人類編寫代碼。 PHP口譯員不會(huì)閱讀評(píng)論，但是維護(hù)您的代碼的人肯定會(huì)這樣做。

以上是用結(jié)構(gòu)化php塊評(píng)論製作可維護(hù)的代碼庫(kù)的詳細(xì)內(nèi)容。更多資訊請(qǐng)關(guān)注PHP中文網(wǎng)其他相關(guān)文章！