go語言的注釋編碼規(guī)范有哪些

這篇文章主要介紹“go語言的注釋編碼規(guī)范有哪些”，在日常操作中，相信很多人在go語言的注釋編碼規(guī)范有哪些問題上存在疑惑，小編查閱了各式資料，整理出簡單好用的操作方法，希望對大家解答”go語言的注釋編碼規(guī)范有哪些”的疑惑有所幫助！接下來，請跟著小編一起來學(xué)習(xí)吧！

注釋編碼規(guī)范：1、所有導(dǎo)出對象都需要注釋說明其用途；非導(dǎo)出對象根據(jù)情況進(jìn)行注釋。2、如果對象可數(shù)且無明確指定數(shù)量的情況下，一律使用單數(shù)形式和一般進(jìn)行時描述；否則使用復(fù)數(shù)形式。3、包、函數(shù)、方法和類型的注釋說明都是一個完整的句子。4、句子類型的注釋首字母均需大寫；短語類型的注釋首字母需小寫。5、注釋的單行長度不能超過80個字符。

注釋的意義

• 注釋可以幫我們很好的完成文檔的工作，寫得好的注釋可以方便我們以后的維護(hù)。

• /**/ 的塊注釋和 // 的單行注釋兩種注釋風(fēng)格， 在我們的項目中為了風(fēng)格的統(tǒng)一，全部使用單行注釋，注釋的質(zhì)量決定了生成的文檔的質(zhì)量。

注釋規(guī)范

• 所有導(dǎo)出對象都需要注釋說明其用途；非導(dǎo)出對象根據(jù)情況進(jìn)行注釋。

• 如果對象可數(shù)且無明確指定數(shù)量的情況下，一律使用單數(shù)形式和一般進(jìn)行時描述；否則使用復(fù)數(shù)形式。

• 包、函數(shù)、方法和類型的注釋說明都是一個完整的句子。

• 句子類型的注釋首字母均需大寫；短語類型的注釋首字母需小寫。

• 注釋的單行長度不能超過80個字符。

1、包級別

包級別的注釋就是對包的介紹，只需在同個包的任一源文件中說明即可有效。

• 每個包都應(yīng)該有一個包注釋，一個位于 package 子句之前行注釋

• 包注釋應(yīng)該包含下面基本信息

// @Title  請?zhí)顚懳募Q（需要改）
// @Description  請?zhí)顚懳募枋觯ㄐ枰模?
// @Author  請?zhí)顚懽约旱恼媸切彰ㄐ枰模?nbsp; ${DATE} ${TIME}
// @Update  請?zhí)顚懽约旱恼媸切彰ㄐ枰模?nbsp; ${DATE} ${TIME}
package ${GO_PACKAGE_NAME}

2、結(jié)構(gòu)（接口）注釋

每個自定義的結(jié)構(gòu)體或者接口都應(yīng)該有注釋說明，該注釋對結(jié)構(gòu)進(jìn)行簡要介紹，放在結(jié)構(gòu)體定義的前一行，格式為： 結(jié)構(gòu)體名， 結(jié)構(gòu)體說明。同時結(jié)構(gòu)體內(nèi)的每個成員變量都要有說明，該說明放在成員變量的后面（注意對齊），實例如下：

// User   用戶對象，定義了用戶的基礎(chǔ)信息
type User struct{
    Username  string // 用戶名
    Email     string // 郵箱
}

3、函數(shù)（方法）注釋

• 每個函數(shù)，或者方法（結(jié)構(gòu)體或者接口下的函數(shù)稱為方法）都應(yīng)該有注釋說明

• 函數(shù)的注釋應(yīng)該包括三個方面

// @title    函數(shù)名稱
// @description   函數(shù)的詳細(xì)描述
// @auth      作者             時間（2019/6/18   10:57 ）
// @param     輸入?yún)?shù)名        參數(shù)類型         "解釋"
// @return    返回參數(shù)名        參數(shù)類型         "解釋"

4、代碼邏輯注釋

• 每個代碼塊都要添加單行注釋

• 注視使用 TODO 開始 詳細(xì)如下

// TODO  代碼塊的執(zhí)行解釋
if   userAge < 18 {

}

其它說明

• 當(dāng)某個部分等待完成時，可用 TODO: 開頭的注釋來提醒維護(hù)人員。

• 當(dāng)某個部分存在已知問題進(jìn)行需要修復(fù)或改進(jìn)時，可用 FIXME: 開頭的注釋來提醒維護(hù)人員。

• 當(dāng)需要特別說明某個問題時，可用 NOTE: 開頭的注釋：

  // NOTE: os.Chmod and os.Chtimes don't recognize symbolic link,
  // which will lead "no such file or directory" error.
  return os.Symlink(target, dest)

到此，關(guān)于“go語言的注釋編碼規(guī)范有哪些”的學(xué)習(xí)就結(jié)束了，希望能夠解決大家的疑惑。理論與實踐的搭配能更好的幫助大家學(xué)習(xí)，快去試試吧！若想繼續(xù)學(xué)習(xí)更多相關(guān)知識，請繼續(xù)關(guān)注億速云網(wǎng)站，小編會繼續(xù)努力為大家?guī)砀鄬嵱玫奈恼拢?/p>