コメント（// と /* */）

// 一行コメント — // から行末までがコメントになります。
var x int = 10 // 行末コメント — コードの後にも書けます。

/*
   ブロックコメント — /* から */ までの範囲がコメントになります。
   複数行にわたるコメントや、コードブロックのコメントアウトに使います。
*/

// ExampleFunc は直後の関数を文書化するコメントです。
// 宣言の直前に /* */ ではなく // で書くのが Go の慣習です。
// コメントは宣言名から始めるのが慣習です（"ExampleFunc は..."）。
func ExampleFunc() {}

// Package math は数学ユーティリティを提供します。
// パッケージコメントはパッケージ宣言の直前に書きます。
package math

Goのドキュメントコメントは特別なタグがなく、書き方の慣習でドキュメント品質が決まります。標準ライブラリのコメントスタイルが参考になります。

『go doc』コマンドでパッケージ・型・関数のドキュメントを表示できます。

go doc fmt
go doc fmt.Println
go doc -all math

comment_basic.go

// comment_basic.go — Go のコメント構文の基本的な使い方です。
package main

import "fmt"

/*
   定数として商品の個数を定義します。
   ブロックコメントはファイル先頭の説明や大きなコードブロックの
   コメントアウトに使うことがあります。
*/
const itemCount = 3

func main() {
	// 商品名と価格の配列を定義します
	items := [itemCount]string{"widget", "gadget", "device"}
	prices := [itemCount]int{1200, 3500, 800} // 税抜価格

	total := 0

	for i := 0; i < itemCount; i++ {
		fmt.Printf("%-10s %5d yen\n", items[i], prices[i])
		total += prices[i]
	}

	fmt.Println("----------")
	fmt.Printf("%-10s %5d yen\n", "Total", total)
}

実行結果は次の通りです。

go run comment_basic.go

widget      1200 yen
gadget      3500 yen
device       800 yen
----------
Total       5500 yen

calculator.go

// Package main はドキュメントコメントの使い方を示すサンプルです。
//
// エクスポートされた関数に // で始まるドキュメントコメントを付けると、
// go doc コマンドで参照できるドキュメントになります。
package main

import (
	"errors"
	"fmt"
)

// Sum は整数スライスの合計値を計算して返します。
//
// スライスが nil の場合はエラーを返します。
func Sum(values []int) (int, error) {
	if values == nil {
		// nil スライスはサポート外のためエラーを返します
		return 0, errors.New("values must not be nil")
	}

	total := 0
	for _, v := range values {
		total += v
	}
	return total, nil
}

// Average は整数スライスの平均値を計算して返します。
//
// スライスが空の場合は 0.0 とエラーを返します。
func Average(values []int) (float64, error) {
	if len(values) == 0 {
		/* 空スライスはゼロ除算になるため早期リターンします */
		return 0.0, errors.New("values must not be empty")
	}

	sum, err := Sum(values)
	if err != nil {
		return 0.0, err
	}

	// 整数除算を避けるためキャストします
	return float64(sum) / float64(len(values)), nil
}

func main() {
	scores := []int{85, 92, 78, 95, 60}

	sum, _ := Sum(scores)
	fmt.Println("Sum:    ", sum)

	avg, _ := Average(scores)
	fmt.Printf("Average: %.1f\n", avg)

	// 空スライスのケース
	_, err := Average([]int{})
	fmt.Println("Empty: ", err)
}

実行結果は次の通りです。

go run calculator.go

Sum:     410
Average: 82.0
Empty:  values must not be empty

Goのコメントは『//』と『/* */』の2種類ですが、ドキュメントコメントとしては通常の『//』をそのまま使います。宣言の直前に書いた『//』コメントを『go doc』や『godoc』が解析してドキュメントを生成します。特別なタグは不要です。

慣習として、エクスポートされた識別子（大文字始まり）には必ずドキュメントコメントを付け、「関数名 は…」のように宣言名から始めます。パッケージコメントは『// Package 名前 は…』の形式で package宣言の直前に書きます。最初の文が要約として使われるため、最初の文だけを読んでも意味が通るように書くことが重要です。