注釋在程序中的作用是對(duì)程序進(jìn)行注解和說明，高程序代碼的可讀性，便于對(duì)源碼的閱讀；目的是為了讓別人和自己很容易看懂，一看就知道這段代碼是做什么用的。go的注釋有行注釋“//”和塊注釋“/* */”之分；在實(shí)際的使用中，行注釋使用得比較多，塊注釋主要用于格式化大段代碼或包的注釋中使用。

本教程操作環(huán)境：windows7系統(tǒng)、GO 1.18版本、Dell G3電腦。

注釋有什么作用

注釋就是對(duì)代碼的解釋和說明，其目的是讓人們能夠更加輕松地了解代碼。注釋是編寫程序時(shí)，寫程序的人給一個(gè)語句、程序段、函數(shù)等的解釋或提示，能提高程序代碼的可讀性。

注釋在程序中的作用是對(duì)程序進(jìn)行注解和說明，便于對(duì)源碼的閱讀。編譯系統(tǒng)在對(duì)源代碼進(jìn)行編譯時(shí)會(huì)自動(dòng)忽略注釋的部分，因此注釋對(duì)于程序的功能實(shí)現(xiàn)不起任何作用。在源碼中適當(dāng)?shù)靥砑幼⑨?，能夠提高源碼的可讀性。

注釋就是對(duì)代碼的解釋和說明。目的是為了讓別人和自己很容易看懂，一看就知道這段代碼是做什么用的。正確的程序注釋一般包括序言性注釋和功能性注釋。序言性注釋的主要內(nèi)容包括模塊的接口、數(shù)據(jù)的描述和模塊的功能。模塊的功能性注釋的主要內(nèi)容包括程序段的功能、語句的功能和數(shù)據(jù)的狀態(tài)。

go 注釋的分類

go 的注釋有行注釋 // 和塊注釋 /* */ 之分。在實(shí)際的使用中，行注釋使用得比較多，塊注釋主要用于格式化大段代碼或包的注釋中使用。

在 goland 中行注釋的快捷鍵為 Ctrl+/, 塊注釋的快捷鍵為 Ctrl+Shift+/

應(yīng)用

文件注釋

在每個(gè)文件中前都加上一段注釋，這段注釋用來描述 作者，時(shí)間，以及版權(quán)。

我們可以隨便打開一個(gè)包查看，如 builtin.go 包中

// Copyright 2011 The Go Authors. All rights reserved. // Use of this source code is governed by a BSD-style // license that can be found in the LICENSE file.

就有時(shí)間 2011, 作者 go，和版權(quán)，我們可以隨便打開其他文件，可以發(fā)現(xiàn)只有時(shí)間在變，而其他都沒有變化。

在 goland 中可以在 Settings/Editor/File and Code Templates/Files/Go File 中尋改文件注釋模板，這樣每次新建文件都會(huì)自動(dòng)生成注釋。

這是我的模板

//@program: ${PROJECT_NAME} //@author: edte //@create: ${YEAR}-${MONTH}-${DAY} ${HOUR}:${MINUTE} package ${GO_PACKAGE_NAME}

包注釋

包注釋用來描述介紹這個(gè)包，以及提供包的一些信息。

在 go 中，一個(gè) 目錄中只有一個(gè)包（不包擴(kuò)子目錄），所以一個(gè)包中可以有多個(gè)文件，一般在其中一個(gè)文件寫上包注釋即可。

同樣的，我們來看 builtin 這個(gè)包 中的 builtin.go 文件

/*     Package builtin provides documentation for Go's predeclared identifiers.     The items documented here are not actually in package builtin     but their descriptions here allow godoc to present documentation     for the language's special identifiers. */

可以看到 builtin 包的作用是給預(yù)定義標(biāo)識(shí)符提供文檔。

我們同樣來看 errors 包中的 errors.go 文件，可以看到包注釋很長(zhǎng)

// Package errors implements functions to manipulate errors.

這里講了包 errors 實(shí)現(xiàn)了一些處理錯(cuò)誤的功能。

// The New function creates errors whose only content is a text message. // // The Unwrap, Is and As functions work on errors that may wrap other errors.

后面還有一大堆，講了 errors 包相關(guān)的文件，原理，應(yīng)用等信息。

如果我們繼續(xù)查看源碼，會(huì)發(fā)現(xiàn)包注釋都是以 package + 一個(gè)動(dòng)詞 開頭的，一般這個(gè)短句就說明了這個(gè)包的功能，然后再視具體的包說明包的其他信息。

函數(shù)注釋

函數(shù)注釋用來描述函數(shù)的功能，以及其他相關(guān)的信息。

我們同樣來看 errros 包中的 errors.go 文件

// New returns an error that formats as the given text. // Each call to New returns a distinct error value even if the text is identical. func New(text string) error {     return &errorString{text} }

這里用一句話說明了 New 功能的作用，即返回一個(gè)自定義的錯(cuò)誤。

然后又用一句話說了這個(gè)函數(shù)相關(guān)的特點(diǎn)，即使文本相同，每次對(duì) New 的調(diào)用也會(huì)返回一個(gè)不同的錯(cuò)誤值。

如果同樣查看其他源碼中的函數(shù)，我們發(fā)現(xiàn)一般幾乎都是 函數(shù)名 + 一個(gè)動(dòng)詞 的句子開頭。這個(gè)句子同樣說明了這個(gè)函數(shù)的作用，即函數(shù)干了些什么。

而其他需要講解的信息則以復(fù)雜度為基礎(chǔ)，如果感覺某個(gè)點(diǎn)不容易理解，那么最好都要寫注釋，如函數(shù)簽名，函數(shù)原理，函數(shù)使用過程中需要注意的點(diǎn)等。

數(shù)據(jù)類型注釋

數(shù)據(jù)類型注釋說明 這個(gè)數(shù)據(jù)類型用來干什么。

如 errors.go 中

// errorString is a trivial implementation of error. type errorString struct {     s string }

這里就說明了 errorString 的作用，即 error 的具體實(shí)現(xiàn)。

如 built.go 中

// bool is the set of boolean values, true and false. type bool bool  // true and false are the two untyped boolean values. const (     true  = 0 == 0 // Untyped bool.     false = 0 != 0 // Untyped bool. )  // The error built-in interface type is the conventional interface for // representing an error condition, with the nil value representing no error. type error interface {     Error() string }

幾乎都是以 類型名 + is 開頭的句子，這個(gè)句子說明了這個(gè)類型的作用。

TODO

TODO 即 to do, 是一個(gè)特殊的注釋，表明在此處有功能等待編寫，

FIXME

FIXME 即 fix me, 也是一個(gè)特殊的注釋，表明此處的功能需要修正，甚至不能運(yùn)行

XXX

XXX 也是一個(gè)特殊的注釋，表明此處的功能實(shí)現(xiàn)方法有點(diǎn)問題，需要更改

godoc

godoc 是一個(gè)實(shí)用的工具，可以根據(jù)特定的注釋格式生成文檔。也可以用來查看文檔，同樣的 go doc 命令也是相似的作用，具體的可以查看這篇文章。

【