Go Wiki: コメント

Go は C スタイルの /* */ ブロックコメントと C++ スタイルの // 行コメントをサポートしています。通常は行コメントが使われます。

ドキュメントコメント

パッケージとエクスポートされた名前にはドキュメントコメントが必要です。ドキュメントコメントは特定の慣例に従い、シンプルな書式設定構文をサポートしています。詳細については、Go Doc Comments を参照してください。

ディレクティブ

go ツールやコンパイラを含む一部のツールは、コメントに出現するディレクティブをサポートしています。互換性のために存在するいくつかの例外を除き、これらのコメントディレクティブは // と go: の間にスペースなしで //go: から始まる行コメントです。

go ツールディレクティブ

//go:build

go ツールはビルド制約をサポートしています。これらは、ファイルがパッケージに含まれるべき条件を記述する //go:build ディレクティブです。

制約の一般的な使用例は次のとおりです。

//go:build ignore は、ファイルがビルドの一部にならないようにするための慣例です。これは、ソースコードを生成するプログラムによく使用されます。
//go:build linux は、Linux 用にビルドする場合にのみファイルをビルドします。これは、任意のオペレーティングシステムまたはアーキテクチャに一般的に使用できます。
//go:build cgo は、cgo がサポートされている場合にのみファイルをビルドします。
//go:build purego は、pure Go を使用する場合にのみファイルをビルドする慣例です。つまり、cgo やアセンブラコードは使用しません。

制約は式にすることもできます

//go:build amd64 || arm64 は、amd64 または arm64 のいずれかでファイルをビルドします。

制約は、ファイルをコンパイルするときに使用する言語バージョンを設定できます。たとえば、//go:build go1.23 という制約は、Go 1.23 以降を使用する場合にのみファイルをビルドし、ファイルをビルドするときに Go 1.23 言語セマンティクスを使用します。これは go.mod が以前のバージョンである場合に便利です。たとえば、これにより Go 1.23 の関数イテレータを提供する関数を定義できますが、Go 1.23 以降でビルドする場合に限られます。

Go 1.16 以前では、ビルド制約は // +build で始まるコメントを使用して記述され、一般的な式は許可されていませんでした。gofmt プログラムは、古い // +build 構文を新しい //go:build 構文に書き換えます。

//go:generate

go generate コマンドは、実行するコマンドを見つけるために //go:generate ディレクティブを探します。

このディレクティブの例としては、//go:generate stringer -type=Enum があります。これは、整数型の値に対して String メソッドを定義するためにstringer ツールを実行するものです。

//go:embed

embed パッケージは、//go:embed ディレクティブを使用してソースファイルを生成されたバイナリに埋め込みます。単一のファイルは string または []byte として埋め込むことができます。ファイルのグループは、fs.FS インターフェースを実装する embed.FS として埋め込むことができます。

たとえば、templates という名前のサブディレクトリの内容は、次のようなディレクティブを使用してプログラムに埋め込むことができます。

//go:embed templates
var templatesSource embed.FS

// tmpls holds the parsed embedded templates.
// This does not read files at run time,
// it parses the data embedded in the binary.
var tmpls = template.ParseFS(templatesSource)

コンパイラディレクティブ

Go コンパイラはいくつかのディレクティブをサポートしています。

//line

//line ディレクティブは、後続のコードに使用するファイル名と行番号、列番号を設定できます。歴史的な理由により、このディレクティブは //go: から始まりません。これは、Go ファイルが他のソースから生成された場合に役立ち、エラーメッセージやスタックトレースが生成されたソースファイルではなく、その他のソースファイルを参照するのに便利です。

行内では、/*line ブロックコメントを使用でき、列位置を設定するのに役立ちます。

//line foo.src:10
var x = /*line foo.src:20:5*/ 3

//go:noescape

//go:noescape ディレクティブの後に、関数本体のない関数宣言が続く必要があります。これは Go で実装されていない関数を示します。このディレクティブは、関数に渡されたポインタがヒープにエスケープせず、関数によって返されないことをコンパイラに伝えます。

その他のコンパイラディレクティブ

特別な目的を果たす他の多くのコンパイラディレクティブがあります。詳細については、コンパイラのドキュメントを参照してください。

//go:linkname
//go:noinline
//go:norace
//go:nosplit
//go:uintptrescapes
//go:wasmimport

未文書化のコンパイラディレクティブ

コンパイラは、一部の未文書化のディレクティブもサポートしています。一般に、これらはユーザーコードで使用すべきではありません。これらのいくつかはりランタイムパッケージをコンパイルする場合にのみ利用可能です。

//go:nocheckptr
//go:nointerface
//go:nowritebarrier
//go:nowritebarrierrec
//go:registerparams
//go:systemstack
//go:uintptrkeepalive
//go:yeswritebarrierrec

cgo コメント

cgo ツールは、import "C" ステートメントの直前に現れる 1 つ以上のコメントのシーケンスを使用します。cgo プレアンブルとして知られるこのコメントのシーケンスは、Go コードが特別な C パッケージを使用して参照できる名前を定義します。

package main

// #include <stdio.h>
import "C"

func main() {
    C.puts(C.CString("hello world"))
}

プレアンブル内では、cgo は #cgo で始まるディレクティブを認識します。これらは、使用する C コンパイラおよびリンカのフラグを設定したり、一部の C 関数の動作を記述したりするために使用できます。詳細については、cgo のドキュメントを参照してください。

cgo export

cgo を使用するファイルでは、//export ディレクティブを使用して Go 関数を C コードから可視にすることができます。構文は Go 関数 GoName の前に現れるコメント内の //export CName です。これにより、C から関数 CName を呼び出すと、実際に Go 関数 GoName が呼び出されるようになります。詳細については、cgo のドキュメントを参照してください。

cgo コンパイラディレクティブ

cgo ツールは Go コードを生成し、その生成されたコードは、主に cgo 生成コードでのみ利用可能な特別なディレクティブを使用します。これらは cgo のソースコード以外ではほとんど文書化されていません。

//go:cgo_dynamic_linker
//go:cgo_export_dynamic
//go:cgo_export_static
//go:cgo_import_dynamic
//go:cgo_import_static
//go:cgo_ldflag
//go:cgo_unsafe_args

このコンテンツはGo Wikiの一部です。