コメント

GoはC形式の/* */ブロックコメントとC++形式の//行コメントを提供します。行コメントが標準です。ブロックコメントはほとんどパッケージコメントとして現れますが、式内で有用であったり、大きなコードブロックを無効にしたりするのに役立ちます。

トップレベルの宣言の前に、間に改行なしで現れるコメントは、宣言自体を文書化するものと見なされます。これらの「docコメント」は、指定されたGoパッケージまたはコマンドの主要な文書です。docコメントの詳細については、「Go Docコメント」を参照してください。

パッケージコメント

すべてのパッケージにはパッケージコメントが必要です。これは、package句の前にあるブロックコメントです。複数ファイルのパッケージの場合、パッケージコメントは1つのファイルにのみ存在すれば良く、どのファイルでも構いません。パッケージコメントはパッケージを紹介し、パッケージ全体に関連する情報を提供する必要があります。これはgodocページで最初に表示され、その後に続く詳細な文書の設定を行います。

/*
regexp パッケージは正規表現のためのシンプルなライブラリを実装します。

受け入れられる正規表現の構文は：

    regexp:
        concatenation { '|' concatenation }
    concatenation:
        { closure }
    closure:
        term [ '*' | '+' | '?' ]
    term:
        '^'
        '$'
        '.'
        character
        '[' [ '^' ] character-ranges ']'
        '(' regexp ')'
*/
package regexp

パッケージが簡単な場合、パッケージコメントは簡潔になることがあります。

// path パッケージはスラッシュで区切られたファイル名パスを
// 操作するためのユーティリティルーチンを実装します。

コメントは星のバナーなどの追加のフォーマットを必要としません。生成される出力は固定幅フォントで表示されない可能性があるため、整列のためのスペーシングに依存しないでください。godocはgofmtと同様にそれを処理します。最後に、コメントは解釈されないプレーンテキストなので、HTMLやその他の注釈（_this_など）はそのまま再現されるため、使用すべきではありません。

パッケージ内では、トップレベル宣言の直前にあるコメントは、その宣言のdocコメントとして機能します。プログラム内のすべてのエクスポートされた（大文字の）名前にはdocコメントが必要です。

Docコメントは完全な英語の文として最も効果的に機能し、さまざまな自動化されたプレゼンテーションを可能にします。最初の文は宣言される名前で始まる一文要約であるべきです。

// Compile は正規表現を解析し、成功した場合、テキストにマッチするために
// 使用できるRegexpオブジェクトを返します。
func Compile(str string) (*Regexp, error)

Goの宣言構文では宣言のグループ化が可能です。1つのdocコメントで関連する定数や変数のグループを紹介できます。全体の宣言が表示されるため、そのようなコメントはしばしば形式的になることがあります。

// パース式の失敗によって返されるエラーコード。
var (
    ErrInternal      = errors.New("regexp: internal error")
    ErrUnmatchedLpar = errors.New("regexp: unmatched '('")
    ErrUnmatchedRpar = errors.New("regexp: unmatched ')'")
    ...
)

グループ化は、アイテム間の関係を示すこともできます。たとえば、一連の変数がミューテックスによって制御されているという事実などです。

var (
    countLock   sync.Mutex
    inputCount  uint32
    outputCount uint32
    errorCount  uint32
)