【プロが教える】コメントの書き方レッスン【コメンティング】

どうも、oyanです。
プログラミングしていると避けては通れない概念。
プログラムコードのコメントについて語りたいと思います。

コメンティングとは？

まず、この記事のタイトルにも使っている「コメンティング」について。

プログラムコードへコメントを付ける作業のこと
を「コメンティング」と定義します。

私が作った用語です。一般的ではありませんの注意。

ですが、私はこの「コメンティング（作業）」の重要性を強く提唱しています。

一般的には、プログラムを作る作業のことを

• プログラミング
• コーディング
• 実装

と呼びます。
この作業にはプログラムを補足する説明（コメント）を付ける作業のことも含んでいます。

従って、「コメンティング」と定義して敢えて分ける必要性があるのか？
と疑問が湧くと思います。

含んでいる・・・
私は、この表現（含んでいる）が違うと思います。

私は、コメントを付ける作業のことを、

「コメンティング」

と呼ぶことにしました！

コメントの特性

「コメント」はプログラムの補足説明なので、
ソフトウェアの動作には関係ありません。

「コメント」を書かなくてもソフトウェアは正しく動作します。

それ故か、

• コメントが付いていない
• 推敲されていないコメントが付いている
• プログラムとコメントが矛盾してる（どっちが正しいの？）

こんな事がよくあります。（いい加減なコメントが付いている）

いい加減なコメントの弊害

いい加減（良い加減ではない）なコメントが付いていると弊害が出てきます。

• このコードの意図はなんだろう？分からない。
• 保守を引き継いだがどうやって修正したら良いか分からない。
• 難しい処理を実装しているこの関数（ライブラリなど）を流用して良いか判断に困る。
• 自分で作ったのになぜこのコードになっているのか思い出せない。

などなど

コメントは誰が何のために付けるのか

なぜコメントを付けるのでしょうか？
そもそも、コメントは必要なのでしょうか？

結論は、
「無くても良い場合」と「あって欲しい場合」がある。
と考えています。

コメントを恒久的に付けなくても良い場合は後述しますが、
コメントが無くても問題ない場合（後々、欲しい場合もある）が存在します。

プログラムを組んでいる（書いている）時、
プログラムを動かしてテストしている時、
プログラムが（テストも終わって）完成しリリースする時、

このタイミングでは、コメントは無くても問題にならないケースが多いと感じます。
理由は単純で、
「記憶が新鮮でコードの意味を把握しているから」
です。
プログラムを作ることは非常に頭を使います。
一生懸命考えて組み上げているプログラムですから、
記憶が新鮮なうちは分からないことなんてありません。

書いたコードが分からないけど、
なんか動いている（気がする）からリリースしよう！
時と場合によりますが、何だかちょっと怖いですよね。

コメントが欲しい場合は、リリース後が非常に多いです。
特に、リリース後にバグが見つかった。機能を追加したり修正したい。
このような場合です。

また、自分や他人が、少し前に作ったプログラムを読む時。
このプログラムは一体どのようになっているのだろうか？を理解したい時。
この時にもコメントが欲しくなります。

理解を助けてくれる。それが、コメントです。
理解を助けてくれないコメントは目的を達成していない「ウンコメント」です。
※ 我々の業界では、「ウンコード」と言う表現が用いられます。

「ウンコード・マニア」なるサイトがあります。

目的を達成していないコメントはコメントにあらず！

美しいコメントを見たことありますか？

実際には、
良いコメントだと感じるプログラムコードに出会うことは少ないです。

なぜか。

• リリースまでに時間が無くなってコメントが疎かになる
• プログラムコード自体が洗練されていないのでコメントも複雑で分かりにくい
• 実動作とは関係ないので手を抜いてしまう
• リリース前は記憶が新鮮なのでプログラムコードに対してコメント（補足）不要と思っている

このような理由が考えられます。

そこでコメンティングの登場

この機能をプログラミングするのに３日掛かるな。
という仕事があったとします。
この場合、プログラミングに３日掛ける。と考えるのではなく、
２日はプログラミング。
１日はコメンティング。
あるいは、
３日はプログラミング。
１日はコメンティング。←１日作業日数が増える

このように、見積もっておきます。
とにかく、１日コメントを付け続ける作業を計画しておくことを強く推奨します。

リリース後にプログラムを弄る？
リファクタリングでは？
いえ、リファクタリングは実動作を変えずに実コードのコードを精査して改良してく事を指しています。
コメンティングはコメントを付けるだけです。

リファクタリングの前にまずコメンティング！

さらに専門的と言いますか、開発プロセスの話になりますが、
リリース後にコメンティングする場合、
アジャイル開発が「是」となっているプロジェクトではやり易いです。

また、
リリース後にソフトウェア更新が容易かどうかによっても、かなり変わります

やり易い順に列挙すると、

1. Webサービス：やり易い！！
2. デスクトップアプリケーション：インストーラ作成とリリースが自動化されている場合
3. デスクトップアプリケーション：インストーラ作成とリリースが自動化されていない場合
4. 組み込み機器：ソフトウェア更新には物交換が必要な組み込み機器は絶望的にやりにくい

他にもスマホアプリとかありますが割愛しました。

コメントのみ修正して実コードを一切弄らないのであれば、
リリース後にコメントのみ修正しても良いと思います。
ただ、実際に世に出るソフトウェアとソースコードが（機械語レベルでは同じでも）違うので、
少し気持ち悪さが残ります。
やはりリリース前にしっかりコメントしておくのが理想的です。

コメントを付けなくても良い場合

コメントを付ける事を推奨していますが、
付けなくても良い場合があります。

• 試作検証段階のプログラムで、捨てる事を前提にしている時
• リファクタリングする事を前提にしてまず動くものを作る時（試作検証とほぼ同じですね）
• １人で作り続けていて、コメントが無くても問題無い！と言い切れるソフトウェアの場合
• 稀に見かけますが、エレガントすぎる美しいコードが作れた場合（実コード自体から単一の意思を感じ取れる）
• リリースしてから保守は絶対に行わない事が確定している時（まずそんなことはありませんが・・・）

このような場合は、コメントを一生懸命に付ける必要はないと思います。

洗練されたコメントを付けるメリット

コメントのコツを意識して１日（半日でも良いです）かけてコメンティングすると、
いろいろな気づきがあります。

• バグを見つける
• バグとは言えないけれど設計上の上手くないところを見つける
• さらに綺麗でエレガントな実装方法を見つける

見つけたら、実コードにもフィードバックしてあげましょう。
コメントも実コードも質がどんどん上がります。

コメントのコツ

Tema Geekに書いてあること

エンジニアのバイブル（私が勝手にそう言っている）である、

のコードコメント章にはこのように書いてあります。

コードコメントは主観的なもの。
詳細なコメントは作者の意図や理由を知る手がかりとなるため大変便利だ。
しかし、古くなったコメントや事実と異なるコメントにはメンテナンスコストがかかる。
コードの理解を著しく妨げることになる。
逆にコメントがない場合は、将来のメンテナンスやAPIの利用者の調査時間が無駄になる。
コメントは欠けている情報やよくない名前を補足する時に使う事が多い。
ただし、コメントは「なぜ」を説明するものであり、「なに」をしているかを説明するものではない。
コメントはあまりにも詳細に書きすぎない。「中庸を知れ」。
チームのコメントのスタイルも時間をかけて決めよう。
何を選ぶかより一貫性の方が重要。
スタイルのガイドはそのスタイルの存在理由を説明したものでなければならない。

Team Geek

何となく、私が書いたことと近しい思想です。
私も、Google社のエンジニアとして働けるかしら（笑）
Googleのエンジニアもコメントに関して真剣に考えて取り組んでいる事が分かります。

ということで、ここからは私が考えるコメントのコツを紹介していきます。
Team Geekが気になる方はこちらの記事もどうぞ。

コードの翻訳は避ける

見たらひと目で分かるコードを日本語に直訳するコメントは避けましょう。
コメント自体も「ユーザの情報を取得する」とコードが「なに」をしているかを書いてしまっていますので、
完全にアンチパターンです。
「なぜ」に着眼点を置く場合は、以下の観点で考えると良いです。

• 「なぜ」この処理なのか（そもそもユーザの情報を取得する理由とは？）
• 「なぜ」このタイミングなのか（このタイミングでユーザの情報を取得するのはなぜなのか？）
• 「なぜ」この関数／引数なのか（この値（ユーザID）でユーザの情報を取得するのは妥当か？）

１行１行のコードに対して上記の着眼点でコメントを付けると、
流石に煩いので実際には１行１行のコードに対して付けるのではなく、
クラスの単位、関数の単位、大きな処理のブロック単位で上記の着眼点でのコメントを付けると良いです。
１行１行のコードへのコメントは、Team Geekにも書いてある通り、
関数名や変数名が分かりにくい場合に補足する程度でつけるべきです。

// ユーザの情報を取得する
getUserInfo( userID );

意図していることをまず書こう

このプログラムコードが意図している事をまず書きましょう。
このプログラムコード自体が「なに」をしているかではなく、
狙いは「なに」か？これが「なぜ」必要なのか？このようなコードに「なぜ」なっているのか？
を意識してコメントしてみましょう。

クラス／メソッド（関数）／処理のブロック単位で概要を書こう

クラスやメソッドに付けるサマリ的なコメントのことを、
よく巷ではヘッダコメントと言われています。
概要がシンプルに語れるかどうかを意識してみましょう。
複雑な日本語になる場合は、きっと複雑（すぎる）関数となっているはずです。

Andをつけない

シンプルさを保つために、「○○と△△」のようにAnd表現になるコメントを避けましょう。
避けられない場合は、その処理や関数が複雑かどうかを再検討しましょう。

意図していない「引数、使い方、動作環境」を書きましょう

意図していることはしっかり書いてあるが、
意図していないことをハッキリと書いてあるコメントは少ないです。
意図していることと意図していないことが曖昧の場合は設計が足りないです。
意図していない「引数の値、使い方、動作環境」は何かをハッキリさせましょう。
そして、
意図していない引数の値が入力されると、
意図していない使い方がされると、
意図していない動作環境で動作させられると、
このコードはどのように振る舞うのか、どうなってしまうのかを書きましょう。
書けない場合は、設計が足りていません。

テストシナリオと期待値を書きましょう

巷では、TDD（テスト駆動型開発）と呼ばれる開発手法の考え方に近いかも知れません。
予め、テストシナリオ（テストケース）とそのテストの期待する動作（期待値）を書くようにしましょう。
書き方としては、
「こういう状態のとき、こういう動作を行えば、こうなることが期待される」
という形式で記述しておくのがオススメです。
参考：Gherkin（テストのための記法の1つ）

将来の自分へのラブレターを送りましょう

今わかっていても、暫くすると忘れる。それが人間です。
将来の自分へのラブレターと思って、丁寧にコメントを付けましょう。
特に、コメントを付けている時は、コードを一番よく分かっている時です。
「分かっている人間」が「分かっている人間」に説明する言葉と、
「分かっている人間」が「分かっていない人間」に説明する言葉だと、
言葉の構成やチョイスが違います。
将来の自分（や他人）は、このコードを分からない人間です。
分からなくなった将来の自分に対して分かってもらえるような愛のあるラブレターを書く気持ちで、
方針や考えていたことをコメント化していくのが大事です。

コメント化が難しいときには

コメントを付けるのが難しく感じる場合、
付けたコメントがシンプルではないと感じる場合は、
おそらく何かが間違っている。と思いましょう。
難しい設計になっていたり、難しいコードになっているはずです。
シンプルな設計やコードにならないか再検討した方が良いでしょう。

失敗したプログラム設計（実装方法）を書いておきましょう

すでに試してみたが上手くいかなかった手法があれば書いておきましょう。

参考にした文献のURLや書籍名を記録しておきましょう

ネット記事を参考にすることが多いと思いますが、元ネタ書いておくと理解の助けとなります。

• サンプルが書かれた程度の参考記事なのか
• 公式ドキュメントから引用してきたコードなのか
• 公式ドキュメントの記述をこう解釈した結果、書かれたコードなのか

これらが分かると、コードに対する捉え方や理解の仕方が変わります。
参考文献の権威や信頼性もコードの質を問う材料となります。

設計資料（図や表）へのリンクを記載することも検討しましょう

プログラムコードに記録できるのは、テキスト(*1)だけなので、
(*1) 機械語に翻訳する機械がテキストファイルを読むのが主流なので
コメントも自然言語によるただのテキスト（文字列）となります。
自然言語というと特に日本語がそうなのですが、曖昧な言い方ができてしまうので、
コメントのみで補足するのが難しいケースもあります。

そこで、ソフトウェアの世界ではUMLが有名ですが、
図で視覚的にソフトウェアの構造や仕組みを表現（モデル化）する設計手法が昔から行われています。
今は、クラウドサービスも発達しているので、
ドローソフトとも呼ばれますが、図を描くWebアプリを活用してソフトウェアを設計してみましょう。
そして、その図へのURLをコメントとして残しておくことも検討してみましょう。
もちろん、技術情報の流出に関しては注意を払って活用していきましょう。

また、AppleのXCODE（統合開発環境）のテキストエディタにて対応されている機能ですが、
MarkDown記法をエディタ上でグラフィカル表示することができます。
個人的にはなかなかイケている機能だと思ってます。

コメントスタイル策定で揉めるテーマ

１行１コメント信者

チームで開発している際に、
コメントのスタイル（コメントの付け方のルール、ガイドライン）を
決めておくと良いのですが、
「１行のコードに対して１行のコメントを付けよ」と言う人が、たまにいます。
私が会社に入社した頃に、１行１コメント！と指導されたことがあります。
例えば、こんな感じです。

// ユーザの情報を取得する
user = getUserInfo( userID );

// お酒の購入に成功したかどうかの結果
bool rslt = false;    // 購入結果

// ユーザが成年か ?
if ( user.age >= 20 )
{
    // お酒を買う事が可能なのでお酒を買う（購入関数へ残金を渡す）
    rslt = BuyLiquorExecution(user.MoneyInPossession)
}
// ユーザが未成年
else
{
    // お酒を買う事は出来ないので購入失敗を返す
    rslt = false;
}
return rslt;

いかがでしょうか？
１行につき１コメントを付けてみました。

コード自体が今思いつきで書いたので、
オブジェクト指向設計的にどうなの？とか
不自然な機能責務で分割してる気がします。

が、コード自体の質はちょっと脇に置いておきます。
（おい！そっちの方が大事だろ）

プログラミングに慣れた方だと、
このようなコメント何か意味あるの？とツッコミそうです。
私も実際にはこのようなコメントは打ちません。

ただ、他人のコードを読む時には実はこのコメントは、
日本人特有のある弱点を補う効果が発生しています。

日本人って英語が苦手ですよね。

苦手意識ありますよね。

おおよそ正しい英語の文法と単語を用いて、
それら文法と単語の意味をスッと解釈できれば、
上記のコードのコメントって不要ですよね。

むしろコメントが邪魔。

だけれど、
英語が苦手な僕たち日本人はコメントがついていると、
日本語なのでスッと解釈しちゃうわけです。

上記のコードのコメントだけを抜粋してみます。

// ユーザの情報を取得する

// お酒の購入に成功したかどうかの結果
// 購入結果

// ユーザが成年か ?
    // お酒を買う事が可能なのでお酒を買う（購入関数へ残金を渡す）
// ユーザが未成年
  　// お酒を買う事は出来ないので購入失敗を返す

ほら！コードがなにやってるかスッと解釈できちゃいましたよね？
私は、この日本語のコメント達を「仮想コード」と呼んでいます。

実コードではないけど仮想的なコードです。
前述しましたけど、実コードをそのまま直訳しているだけです。

英語が苦手なので仮想コードがあると「コード自体が何か」が分かり易いです。
英語圏の人は、ここまで直訳的なコメントは絶対につけないと思います。

でも日本人は・・・英語が苦手・・・しつこい。

ただ、英語の単語は横に長くなりがちなので、
省略して変数名や関数名を付けるのが慣習となってます。
（横にコードが長くなると読みにくくなるので）

超ベリーバットなんだけど！を「チョベリバ！」と省略する感じですね。
（古っ！オッサン扱い覚悟。実際オッサン）

なので、変数名や関数名を補足するコメントを
英語圏の人でも付けている事は多々あります。

少し想像してみてください。
日本語で記述できるプログラミング言語があったら・・・
実際に昔は「ひまわり」とか、
今だと「なでしこ」と言う日本語プログラミング言語があります。

天気は「晴れ」
もし、天気が「晴れ」ならば
　　　「洗濯物を干す」と表示。
違えば
　　　「洗濯物は干さない」と表示。

「なでしこ」でプログラミングするとこのようになります。

どうですか？
１行につき１コメントで「仮想コード」を付ける気になります？

なりませんよね。
つまり、コードを直訳するようなコメントを付ける意味って
あまり無いってことなんです。

ここでは、
なぜ天気が「晴れ」だと洗濯物を干さなければならないのか？
についてコメントを残すべきです。

あるいは、
「曇り」と言う中間的な曖昧な天気の場合は、
本当に洗濯物を干さなくて良いのか？
についてコメントで言及するべきです。

あるいは、
「雨」の場合に、室内で干す。
といった選択肢を取っていない理由をコメントすべきです。

「天気が晴れなら洗濯物を干す」は、
一般常識の範疇と判断するなら、
細かいコメントは不要かも知れません。

しかし、お酒の販売については、
日本では２０歳だけれど、別の国では違うかも知れません。

したがって、動作環境は「日本」を想定していますよね。
しかし、日本以外でも２０歳から買える国ならその国でも使えます。

このように、
１つのコードを取ってみても
頭の中で様々な思考実験が繰り返された成れの果てが、
あの１行のプログラムコードとなるのです。

後々にプログラムコードの理解に迷いを
生じさせる可能性がありそうなコードに対して、
「なぜ」このようなコードに落ち着いているのかを
示す事ができるコメントを付ける事が重要です。

これが意識されているのであれば、
１行１コメント（を目安）にコメントする。
をコメントスタイルに取り入れても問題はないと思います。

ただ、１行１コメントをコメントスタイルに入れると、
どうしても日本人は仮想コードを書きがちになるので
私は止めておいた方が良いと思います。

Authorタグ問題（ソースコードの所有権を主張したいのか？）

ソースコード（ソースファイル）の先頭（つまり１行目）から、
決まり切った定型フォーマットでコメントを付ける。
そのようなコーディングルール（コメントスタイル）についてです。
このコメントスタイルもよく見かけます。このような感じです。

/*
 * 概要：○○管理クラス
 * 説明：システム の起動と停止を行う
 *
 * 著作権  ：Copyright(c) 2025 hoge
 * 会社名  ：hoge株式会社
 *
 * 作成者：T.OYAN(下請け株式会社)
 * 作成日：2025-12-24
 * 変更履歴：
 * 　　Rev.00 2025.12.24 T.OYAN(下請け株式会社)
 * 　　　新規作成
 * 　　Rev.01 2026.01.22 Y.TARO(孫受け株式会社)
 * 　　　障害No[12345] の障害修正。
 * 　　　ユーザIDを２バイトから４バイトへ拡張
 *      （ユーザが65535人以上になったら不味い。の指摘修正）
 * 　　Rev.02 2026.02.01 S.SATO(hoge株式会社)
 * 　　　障害No[23456] の障害修正。
 * 　　　ユーザIDを４バイトから１バイトへ変更
 * 　　Rev.03 2028.05.23 T.OYAN(下請け株式会社)
 * 　　　障害No[34567] の障害修正。
 * 　　　ユーザIDを１バイトから２バイトへ変更
 * 　　　中小企業の社員を管理するのだから６万人を超える大企業にならないだろ！
 * 　　　だけど、255人を超える会社になる可能性があるから２バイトにしたのに、
 * 　　　リリースして数年経ってやっぱり足りなくなったじゃないか！
 * 　　　と言うかなぜ１バイトに変更したんだ。なぜなんだー！！ばかばかばか！！
 */

#include <stdio.h>

このようなヘッダコメント見たことありませんか？
内容は・・・日本のIT産業構造の闇を表現してますが内容はどうでも良いです。
ここで問題としたいのは、作成者の名前を書いておく必要があるのかどうか問題です。

Googleでもこのようなヘッダコメントを入れていたチームがあったそうです。

// # -----------------------------
// # Created: Sep.21 2022 by Steve Jobs
// # -----------------------------

このような感じだそうです。
Team Geekによると、

ソースコードのトップに名前を入れるのはもう古い。
（昔は僕たちもやっていた）
個人でプログラムを書いていた時代なら良かったのかも知れないが、
今だと多くの人たちがプログラムコードに触れる。
ファイルに名前が書かれていると物議を醸す。それは時間の無駄だ。
したがって、ソースコードの所有者としての名前を書くべきではない。
レビューアとして名前を書くのは良い。
演劇・小説・映画などの共同作品とは違い、
ソフトウェアは「完成」した後も変化を続ける。
映画のエンドクレジットは書き換えられることのない静的なものだが、
ソースファイルのクレジットを変更しようとすると
永久に書き換えることになるだろう。

Team Geek

と書かれている。
多数の人がソースコードが書かれているファイルを触るのに、
作成者を記載しておく必要がどこになるのだ？ってことです。

だが、ここで１つ注意点。
ヘッダコメントを付ける必要性には言及はされてません。
ヘッダコメント内に作成者を書く必要はない。とGoogleのエンジニアは言ってます。
実際、レビューアの名前は書いても良い。とのこと。
私も同意見です。

さらに、私は、変更の履歴はヘッダコメントとして書いておいた方が良いと考えています。
中には、gitやSVNといったソースファイルを管理するシステムにて
変更履歴に相当するコミットログを記載するのだからヘッダコメント自体不要！
とまで主張する人もいます。
変更の履歴が２重管理となって無駄だ！

確かに一理あります。

私は、ヘッダコメントに履歴を入れることにより、
ソースファイルの修正者が、
最新のソースファイルを取得せずに修正を開始してしまう事故を防ぐために、
ヘッダコメントに必ず履歴を入れるルールを作るべき。と主張しています。

これはどういうことかと言うと、
ヘッダコメントの定位置に変更履歴を追記していくルールがあると、
最新のソースファイルを取得せずに変更履歴を追記すると、
SVNやgitへコミット（gitではPush）するとソースファイルが必ず衝突（コンフリクト）するので、
最新のソースファイルを取得（gitだとPull）していないことに気がつく事ができます。
もちろん、gitだとPullリクエストとtagの切り方を工夫して、
ソースファイルの結合（マージ）に失敗して不整合なコードとならないような工夫は可能です。
とはいえ、私はgitの運用とヘッダコメントへの変更履歴によって２重で事故が起きないように保険をかけておきたい。
そんな思いがあるので、ヘッダコメントに変更履歴を書くことを推奨しています。
もちろん。作成者を入れるのは不要だと思います。

まとめ（この熱い想い伝わってほしい）

このコメンティングに関する想い。
会社の飲み会の時などに語っているのですが、なかなか同業者に伝わらないのです。
熱すぎるのか、それとも説明が悪いのか、それともアルコールが悪いのか。

GoogleでもAppleでもAmazonでも、
たくさんのソフトウェア開発者が在籍して日々ソフトウェアを作り保守メンテナンスしています。
そして、世界を変えていってます。

そして今、
これまでプログラミングとは無縁だった人たちが、
次々とプログラミングに挑戦していると思います。
AIを使っていこう！そんな世の中ですから。

プログラミングに付き物のコメントに対する考えをしっかり持っていく事が、
質の良いソフトウェアを作り維持することに繋がると信じてます。

ソフトウェアが（ほんの少しだけ）みなさんの世界を変える。
その世界が良くなるためにも、質の良いソフトウェアが沢山世の中に提供されていく事を願っています。