「Go言語のコメントの書き方」基本から効果的な使い方まで徹底解説！-Next Hello

この記事では、Go言語のコメントの書き方について、基本のキから、コードが見違えるほど分かりやすくなる効果的な使い方まで、まるっと解説していきますよ！

「コメントって、そもそも何のために書くの？」
「書き方は分かったけど、どんな風に書けば『良いコメント』になるんだろう？」

そんな疑問をこの記事でスッキリ解消しちゃいましょう！

プログラミングの世界に足を踏み入れたばかりの方でも、安心して読み進められるように、難しい言葉は使わずに、サンプルを交えながら楽しく説明していきます。

この記事で学べること

Go言語のコメントがなぜ必要なのか
コメントの基本的な書き方（2種類！）
どんな時にコメントを書くと良いのか
コードが読みやすくなるコメントのコツ
コメントを使う上でのちょっとした注意点
Go言語ならではのドキュメント用コメントの基本

Go言語のコメントとは？なぜ書く必要があるの？

まずは基本からいきましょう！Go言語のコメントとは、プログラムのコードの中に書き込むことができる、人間向けのメモ書きのことです。

コンピューター（Goコンパイラ）はコメント部分を完全に無視するので、プログラムの実際の動きには全く影響を与えません。

じゃあ、なんでわざわざ書くの？って思いますよね。理由はいくつかあります。

コードが読みやすくなる
後で自分が見返したときや、他の人がコードを読むときに、「この部分は何をしている処理なのか」が一目で理解しやすくなります。特に複雑な処理にはコメントがあると助かりますよね。
コードの意図を伝えられる
「なぜこのような書き方をしたのか」という、コードだけでは読み取れない背景や意図を説明できます。
一時的にコードを無効化できる（コメントアウト）
デバッグ（間違い探し）のときなど、一時的に特定のコードを実行させたくない場合に、コメントにしてしまうテクニックがあります。

料理でいうレシピのメモみたいなものですね。材料や手順だけじゃなく、「ここは焦げ付きやすいから注意！」みたいなメモがあると、失敗しにくくなるのと同じです。

良いコメントは、未来の自分や仲間を助ける、思いやりのしるしなんですよ。

Go言語コメントの基本的な書き方 - 2種類を覚えよう

Go言語のコメントの書き方には、大きく分けて2つの種類があります。

「単一行コメント」と「複数行コメント」です。使いどころが少し違うので、まずはこの2つの形と使い方をしっかり覚えちゃいましょう！

単一行コメント (//) の書き方

一番よく使うのが、この単一行コメントです。行の途中に `//` を書くと、そこから行の終わりまでがコメントになります。短い説明や、特定の行に対する注釈を入れたいときに便利です。

書き方はとってもシンプル！

package main

import "fmt"

func main() {
    // これは単一行コメントです。画面にメッセージを表示します。
    fmt.Println("Hello, Go Comment!") // この行の処理内容を説明するコメント

    // price := 100  // ← このように行全体をコメントにすることも可能
}

上の例では、`//` から右側の文字はすべてコメントとして扱われます。プログラムの動作には影響しません。行の途中からでも書けるのがポイントですね。

複数行コメント (/* */) の書き方

次に、複数行にわたってコメントを書きたい場合に使うのが、複数行コメントです。`/*` で始まり、`*/` で終わるまでの範囲がすべてコメントになります。

関数の説明や、少し長めの注釈、あるいは一時的にまとまった範囲のコードを無効化したい（コメントアウトしたい）ときなどに使います。

package main

import "fmt"

/*
これは複数行コメントの例です。
このプログラムは、簡単な挨拶を
画面に表示する機能を持っています。
main関数から処理が始まります。
*/
func main() {
    fmt.Println("Hello, Multi-line Comment!")

    /*
    以下の部分は現在使用していません。
    name := "Go Programmer"
    fmt.Println("Hello,", name)
    */
}

このように、`/*` と `*/` で囲まれた部分は、改行を含めてすべてコメント扱いになります。プログラムから一時的に除外したいコードを囲むのにもよく使われますよ。

効果的なGo言語コメントの書き方 - 読みやすいコードのために

コメントの書き方が分かったところで、次は「どんなコメントを書けばいいの？」というお話です。ただ書けば良いというわけではなく、読みやすいコードにするための「良いコメント」を書くことが目標です。

やみくもにコメントを増やすのではなく、必要な場所に、的確な情報を書くのがコツ。「コードを見ればわかること」をそのままコメントに書いても、あまり意味がない場合が多いです。むしろ、コードが変更されたときにコメントを修正し忘れると、嘘の情報になって混乱を招くことも…。

良いコメントは、コードの「なぜ？」や「何？」を補足してくれるものです。目指すのは、コメントとコードが一体となって、処理の流れや意図がスムーズに理解できる状態です！

コメントを書くべき具体的なケース

じゃあ、具体的にどんな時にコメントを書くと効果的なんでしょうか？いくつか例を挙げてみますね。

複雑な処理の要約
何ステップにもわたる複雑な計算や、分かりにくいアルゴリズムを使っている部分には、「ここで何を実現しようとしているのか」を簡潔に説明するコメントがあると、コードを読む人の負担がぐっと減ります。
コードの意図の説明
一見すると「なんでこんな書き方してるの？」と疑問に思うようなコードには、その理由や背景を説明するコメントが有効です。「パフォーマンスのために、あえて冗長な書き方をしています」とか、「特定のバグを回避するための処理です」のように書きます。
関数の説明（特に公開するもの）
その関数が何をするためのものなのか、引数（入力）として何を受け取り、戻り値（出力）として何を返すのか、などを説明します。これは後で説明する`godoc`にも繋がってきます。
TODOやFIXMEマーカー
「後で修正が必要な箇所」に `// TODO: 〇〇を修正する` と書いたり、「バグがあるけれど、今は応急処置で、後で直す必要がある箇所」に `// FIXME: 〇〇の問題を解決する` と書いたりします。チームで開発しているときや、後で自分が忘れないようにするための目印ですね。
単位や前提条件の説明
例えば、変数 `timeout` があったとして、それがミリ秒なのか秒なのか、コメントで `// timeout はミリ秒単位` と書いておくと誤解を防げます。

コードだけでは伝わらない補足情報をコメントで書く、という意識が良いかもしれません。

良いコメントと避けるべきコメントの例

百聞は一見にしかず！具体的なコード例で、良いコメントと、うーん…なコメントを見てみましょう。

良くない例（コードを見ればわかるコメント）

// 変数 i に 1 を足す
i = i + 1

↑これは、コードを見れば明らかですよね。こういうコメントは、なくても良い場合が多いです。

良い例（コードの意図を説明するコメント）

// タイムアウト発生回数を記録する
timeoutCount = timeoutCount + 1

↑変数名からもある程度推測できますが、「なぜここでインクリメント（+1）しているのか」の意図がコメントによってより明確になります。

良くない例（情報が古いコメント）

// 消費税5%で計算する（古いコメント）
priceWithTax = price * 1.10 // ← コードは10%になっている！

↑コメントとコードの内容が食い違っています。これは一番やってはいけないパターン。混乱のもとです。コメントもコードの一部と考え、修正が必要です。

良い例（複雑な処理の要約）

// クイックソートを使ってユーザーリストを名前順に並び替える
func sortUsersByName(users []User) {
    // (クイックソートの複雑な実装が続く...)
}

↑関数の冒頭で、「この関数全体で何をやっているのか」をコメントで示しておくと、詳細な実装を読む前に概要を把握できます。

どうでしょう？良いコメントは、コードを読む人の理解を助ける「道しるべ」のような役割を果たします。常に「これを読む人は、このコードの背景を知らないかもしれない」という視点を持つと、良いコメントが書けるようになるはずです。

Go言語コメントの便利な使い方と注意点

コメントはメモ書き以外にも、ちょっとした便利な使い方があります。それと同時に、いくつか気をつけておきたい点もあるので、合わせて紹介しますね。

コードのデバッグに役立つ「コメントアウト」

プログラミングをしていると、「あれ、なんかうまく動かないぞ？」って場面が必ず出てきます。

そんな時、原因を特定するために、

「怪しい部分のコードを一時的に実行しないようにする」

というテクニックがよく使われます。これが「コメントアウト」です。

コードを削除してしまうと、後で元に戻すのが大変だったり、やっぱり必要だった！ってなったりしますよね。

コメントアウトなら、`//` や `/* */` を付け外しするだけで、簡単にコードを有効にしたり無効にしたりできます。

単一行コメントでコメントアウト

package main

import "fmt"

func main() {
    fmt.Println("処理A")
    // fmt.Println("処理B") // ← この行を一時的に無効化
    fmt.Println("処理C")
}

// 実行結果:
// 処理A
// 処理C

↑ `処理B` の行頭に `//` を追加するだけで、`処理B` は実行されなくなりました。

複数行コメントでコメントアウト

package main

import "fmt"

func main() {
    fmt.Println("処理A")
    /*
    fmt.Println("処理B-1") // ←
    fmt.Println("処理B-2") // ← まとめて無効化
    fmt.Println("処理B-3") // ←
    */
    fmt.Println("処理C")
}

// 実行結果:
// 処理A
// 処理C

↑ `/*` と `*/` で囲むことで、複数の行をまとめてコメントアウトできます。デバッグの際に、「このブロックが原因かな？」と切り分けるのに便利です。

コメントアウトは非常に便利ですが、デバッグが終わったら不要なコメントアウトは消すのを忘れないようにしましょう。

残しておくと、後で見たときに「なんでこれコメントアウトされてるんだっけ？」と混乱の原因になります。

Go言語のドキュメンテーションコメント (godoc) の基本

Go言語には、コードと一緒にドキュメント（説明書）も管理しやすくするための仕組みがあります。それが `godoc` という機能です。

特定のルールに従ってコメントを書くと、そのコメントを使って自動的に綺麗なドキュメントページを生成してくれるんです。自分で一からドキュメントを作る手間が省ける、とても便利な機能！

特に、他の人も使うようなパッケージ（部品）や関数を作る場合には、この `godoc` 用のコメントを書いておくのがGo言語の作法とされています。

基本は簡単。公開したい（他のファイルから使われる可能性がある）関数や型、変数などの宣言の「直前」に、その名前から始まるコメントを書くだけです。

簡単な例:

package greeting

import "fmt"

// Hello は、指定された名前に対して挨拶を返します。
// nameが空の場合は "Hello, Guest!" を返します。
func Hello(name string) string {
    if name == "" {
        return "Hello, Guest!"
    }
    return fmt.Sprintf("Hello, %s!", name)
}

// Farewell は、別れの挨拶を返します。
func Farewell(name string) string {
	// (実装は省略)
	return "Goodbye!"
}

// MyInt は独自に定義した整数型です。（型の説明例）
type MyInt int

↑このように、`// 関数名は〜` や `// 型名は〜` という形式で、公開する要素の直前にコメントを書きます。複数行にわたる説明も書けます。

この `godoc` コメントを書いておくと、`go doc` コマンドやWebサーバー機能を使って、下のようなドキュメントを簡単に見られるようになります。（実際の表示とは異なりますがイメージです）

PACKAGE DOCUMENTATION

package greeting

FUNCTIONS

func Farewell(name string) string
    Farewell は、別れの挨拶を返します。

func Hello(name string) string
    Hello は、指定された名前に対して挨拶を返します。
    nameが空の場合は "Hello, Guest!" を返します。

TYPES

type MyInt int
    MyInt は独自に定義した整数型です。（型の説明例）

今回は「こんな機能があるんだな」くらいでOKです。Go言語ではコメントがドキュメントにもなる、という点を覚えておくと、今後ステップアップしていく上で役立ちますよ！

【まとめ】Go言語のコメントを理解して分かりやすいコードを書こう！

お疲れ様でした！今回はGo言語のコメントについて、基本的な書き方から、効果的な使い方、ちょっとした注意点まで見てきました。

もう一度、ポイントをおさらいしておきましょう。

コメントは `//` (単一行) と `/* */` (複数行) の2種類。
コメントはコードの可読性を上げ、意図を伝えるために書く。
コードを見ればわかることより、「なぜ」「何」を補足するコメントが良い。
コメントアウトはデバッグに便利だけど、不要になったら消そう。
`godoc` を意識したコメントを書くと、ドキュメント生成に役立つ。
コメントもコードの一部！常に最新の状態に保つ意識を持つ。

コメントは、プログラムの動作には直接関係ないけれど、コードの品質や開発効率に大きく影響します。最初は「どこに書けばいいの？」と迷うかもしれませんが、今回学んだことを意識しながら、まずは書いてみることから始めてみてください。

分かりやすいコメントが書けるようになると、コードを書くのがもっと楽しくなりますし、将来の自分やチームメンバーから、きっと感謝されますよ！

さあ、今日からあなたのGoコードに、素敵なコメントを添えてみませんか？

【関連記事】 Go言語とは？特徴・できること・将来性

「Go言語のコメントの書き方」基本から効果的な使い方まで徹底解説！