go語言的注釋編碼規范有哪些

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

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

注釋的意義

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

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

注釋規范

• 所有導出對象都需要注釋說明其用途；非導出對象根據情況進行注釋。

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

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

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

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

1、包級別

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

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

• 包注釋應該包含下面基本信息

// @Title  請填寫文件名稱（需要改）
// @Description  請填寫文件描述（需要改）
// @Author  請填寫自己的真是姓名（需要改）  ${DATE} ${TIME}
// @Update  請填寫自己的真是姓名（需要改）  ${DATE} ${TIME}
package ${GO_PACKAGE_NAME}

2、結構（接口）注釋

每個自定義的結構體或者接口都應該有注釋說明，該注釋對結構進行簡要介紹，放在結構體定義的前一行，格式為： 結構體名， 結構體說明。同時結構體內的每個成員變量都要有說明，該說明放在成員變量的后面（注意對齊），實例如下：

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

3、函數（方法）注釋

• 每個函數，或者方法（結構體或者接口下的函數稱為方法）都應該有注釋說明

• 函數的注釋應該包括三個方面

// @title    函數名稱
// @description   函數的詳細描述
// @auth      作者             時間（2019/6/18   10:57 ）
// @param     輸入參數名        參數類型         "解釋"
// @return    返回參數名        參數類型         "解釋"

4、代碼邏輯注釋

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

• 注視使用 TODO 開始 詳細如下

// TODO  代碼塊的執行解釋
if   userAge < 18 {

}

其它說明

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

• 當某個部分存在已知問題進行需要修復或改進時，可用 FIXME: 開頭的注釋來提醒維護人員。

• 當需要特別說明某個問題時，可用 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)

到此，關于“go語言的注釋編碼規范有哪些”的學習就結束了，希望能夠解決大家的疑惑。理論與實踐的搭配能更好的幫助大家學習，快去試試吧！若想繼續學習更多相關知識，請繼續關注億速云網站，小編會繼續努力為大家帶來更多實用的文章！