コメントの正しい書き方とは？—読みやすく、伝わるコードにするためのルールとコツ
山崎講師
こんにちは。ゆうせいです。
プログラミングの中で地味だけどとても大事な要素のひとつがコメントです。
あなたもこんな風に思ったことはありませんか？
- 「コメントってどこまで書けばいいの？」
- 「書きすぎると逆に読みにくくなるって本当？」
- 「ルールとかあったりするの？」
実は、コメントにはしっかりとした“書き方のルール”や“ベストプラクティス”が存在します。
この記事では、初心者がよく悩む「コメントの正しい使い方」について、例を交えて丁寧に解説します！
コメントとは何のためにあるのか？
まず大前提として、コメントは「コードの補足説明を人間向けに書くもの」です。
つまり、コンピュータではなく“他の開発者”や“未来の自分”に向けて書くメッセージなんですね。
たとえばこんなことを伝えるために使われます：
- なぜこの実装にしたのか（理由や背景）
- 処理の概要やアルゴリズムの流れ
- 特殊な仕様や制限、注意点
コメントの目的は「安心させること」
コメントの理想は、他の人がコードを読んだときに「なるほど、そういう意図か」と安心できることです。
コメントの種類と書き方のルール
では、具体的にどんな書き方があるのか見ていきましょう。
① 単一行コメント（行頭に // や # を付ける）
ほとんどの言語で使える基本的な形式です。
# 変数xはユーザーの入力値を格納する
x = input("名前を入力してください：")
② 複数行コメント（/* */ や """ """ など）
少し長めの説明をしたいときに使います。
/*
この関数はユーザーIDをもとに
ユーザー情報をデータベースから取得する
*/
function getUserInfo(id) { ... }
Pythonでは """ """ を使いますが、関数の先頭に使うとドキュメンテーション文字列（docstring）になります。
良いコメントと悪いコメントの違い
良いコメントの例：
# ユーザーの年齢に応じて価格を割引する
if age < 18:
price *= 0.8 # 20%引き
悪いコメントの例：
# 年齢が18歳未満なら価格を割引する
if age < 18:
price = price * 0.8 # 価格に0.8を掛ける
一見、問題なさそうに見えるかもしれませんが…
コードとまったく同じことを繰り返しているだけです。これは「ノイズコメント」と呼ばれ、かえって読みづらくなります。
コメントのベストプラクティス（言語に共通するルール）
1. 「なぜ」そのコードなのかを説明する
何をしているかではなく、「なぜそうしたのか」が最重要です。
# 旧APIはタイムアウトが長すぎるため、新APIに切り替え
response = new_api.request()
2. 誤解を防ぐために制約を書く
// 注意：この関数は非同期APIがまだ準備されていないと失敗する
3. コードが十分に読みやすければコメントは控える
良い変数名・関数名を書けば、コメントはいらないことも多いです。
# 悪い例
# ユーザーが有効かどうかを確認する
if user.is_active(): ...
# 良い例（コメント不要）
if user.is_active(): ...
4. TODOコメントを活用する
将来的な課題や追加タスクには、TODOコメントを明記すると便利です。
# TODO: ログイン失敗時のリトライ処理を追加する
言語ごとのスタイルガイドにも注目！
多くの言語には「コメントの書き方を含むスタイルガイド」が用意されています。
| 言語 | コメントスタイルガイド | 特徴 |
|---|---|---|
| Python | PEP 8 | docstringや#コメントの使い分けが推奨 |
| JavaScript | Airbnb Style Guide | コメントは最小限＋意図に集中 |
| Go | Effective Go | パッケージコメントや関数コメントが重視される |
| Java | Javadoc形式 | /** ... */ を用いたドキュメント生成対応 |
よくある質問
Q. 「すべての関数にコメントをつけるべき？」
→ 説明が必要な複雑な関数にはつけるべきですが、短くて明快な関数には不要なことも多いです。
コメントより「良い名前」の方が重要です。
Q. 「日本語で書いてもいいの？」
→ チームによりますが、開発者全員が読める言語で書くことが原則です。
グローバルなプロジェクトなら英語が無難ですが、日本国内であれば日本語でも問題ありません。
結論：コメントは「読み手への思いやり」
コメントを書く目的は、「未来の誰か」がコードを読んだときに、安心して理解できるようにすることです。
- 「なぜこの実装なのか」を伝える
- 「何に注意すべきか」を伝える
- 説明しなくても分かるコードには、コメントを書かない勇気も大切
今後の学習の指針
次のステップとしておすすめなのは、docstringやJavadocなどの「ドキュメントとしても使えるコメントの書き方」です。
また、コメントの質を高めるには、「他人のコードを読む」経験がとても役立ちます。
- GitHubの人気プロジェクトを読んでみる
- 他人のPull Requestをレビューする
そんなところから、「伝わるコメントとは何か」が自然と見えてきます。
他にも「良い命名ってどうするの？」などのテーマもありますので、気になることがあればぜひ聞いてくださいね！
セイ・コンサルティング・グループの新人エンジニア研修のメニューへのリンク
投稿者プロフィール
- 代表取締役
-
セイ・コンサルティング・グループ株式会社代表取締役。
岐阜県出身。
2000年創業、2004年会社設立。
IT企業向け人材育成研修歴業界歴20年以上。
すべての無駄を省いた費用対効果の高い「筋肉質」な研修を提供します！
この記事に間違い等ありましたらぜひお知らせください。
