🖊️テーマ
「Why（なぜ）しか書かない」というストイックな派閥から、「初心者への優しさでWhat（何）も書く」という派閥まで、現場のこだわりを幅広く募集します！📮
👤運営メンバーの回答
運営メンバーのコメント流儀は「未来の自分へのメッセージとして、あえて恥部を書く」でした！ 「なぜこんなに複雑なコードになったのか」「本当はこう書きたかったが、締切の関係でこうなった」という経緯（Why）を自虐を交えて残しておくことで、後で見返した時の自分やチームメンバーを助けているとのこと！
〜teratailトーク!とは？〜
詳細を公式ブログで公開しています。ぜひお読みください。
「teratailトーク!」スタート🎉 気軽に意見交換しよう！
回答14件
#1
総合スコア23720
投稿2026/01/04 23:14
Whyはよく書きますね。「前任者のcodeの関係でこんなになってしまった」「このタイミングでこんな仕様変更するなよ」的な愚痴も。。。
Whatはできるだけ 命名 でわかるように心がけてますが、なにぶん「英語では不自由しなかった(注１)関係で語彙不足な時はコメントします。
ややこしいcodeでリファクタする元気がないときは Howも残します。
注１ 「英語には」ではなくて、「では」です。
英語が必要な場面が仕事でほぼなかった期間が長かったのです。
#2
総合スコア12379
投稿2026/01/05 01:20
編集2026/01/05 06:39【「具体実装を」読めばわかるだろ】なんて話は個人的には馬鹿馬鹿しいというか，怠慢というか，そんなふうに感じる．
（コメントで示さないならば，別の何らかの手段で知ることができるべきではなかろうか？ という理想論のような何か……）
あと，そのコードが読まれている理由次第では，そもそもその具体実装ってのは信用できるんですか？って状況かもしれないわけですし，そこの コードを わざわざ誰かが頑張って解読して What を 推測 しなきゃならない状況って，割と詰んでませんかね？ （すごくつらい状況に思える）
……とかなんとかいうのは置いとくとしても
読めばわかる
って言い方，主語が（意図的に？）抜けてますよね．
「誰が」読むんですかね？ 「どんな人ならば」わかる想定なんですかね？
要不要なんてのはそこんところの想定次第で変わるんじゃないですかね．
私は，少しでも必要だと思うなら何でもとりあえず書く派．
将来にそれを読んだ者（：そのコードの面倒を見ることになった者）がそれを不要だと判断するならば，単にそこで削除なりすればいいだけだと思うし．
#3
総合スコア15
投稿2026/01/05 02:45
「コードを読めばわかるコメント」
コードを読めば、「何が」わかるか次第で変わると思いますが、
- What/How（何をしているか・どう動くか）はコードで表現すべき
- Why/Context（なぜそうしたか・どんな前提や制約があるか）はコメントに残すべき
という考えです
#4
総合スコア283
投稿2026/01/05 02:55
直感的には（頭の中の設計図・自身の実現想定では）こう書いた方がいいだろうな、と思っても、別の書き方が必要になるケース では、なぜその実装にしたのかをコメントに残すようにしています。
例えば、レガシーで大規模なシステムをリプレイスをするときなんかは、 DB のリプレースまではできないこともしばしばありまして・・・
このレガシーなシステムの DB では関連するテーブル同士が外部キー制約で結び付けられていないことも多々あります。
この状況下では、ORMapper のような高機能で便利なライブラリを使用しても、リレーションが張られていないことによってライブラリの便利なメソッドを利用できず、直感に反した書き方を余儀なくされます・・・大体は、生の SQL を書くことになります。
私は TypeScript でバックエンドシステムを作っていますので、 prisma を利用することが多いのですが、prisma の join なんかはリレーションが張られていなければ join を使っての取得ができず、 queryRaw を使って書くことになります。
同じく prisma に詳しい開発者が、この機能に修正を加えることになる際、おそらく join が使われているはずだろう、と思うでしょう。しかし実際にはそうではないのです。
こうした状況のときには、なぜそうしたのかをコメントで残してあげた方が、そうせざるを得なかった理由を後続の開発者に伝えられるため、状況把握に脳のリソースを使わなくてもよくなります。
上記は一例ですが、さまざまなケースにおいて、自身の直感に反して実装をしなければならないときには、コメントを残すようにしています。
#5
総合スコア4427
投稿2026/01/05 03:17
ストイック派閥からコメントします。
基本的に「コードを読めば分かる」インラインコメントは一切書きません。
そうではなくて、コードの形状がコメントと同程度に読めるようになっていないのはプログラマーの敗北なのです。
例えば「X のときは A の処理を行う」は if X then A ですが、コードがその通りの形状になっていなければならないのです。
すなわち、このとき A の処理は A という名前を持った関数に切り出されていなければならず、if X then { XXX; YYY; ZZZ; } はコードとして許容できないわけです。
「何をするか」のコメントに書きたい内容がそのままコードの形状になるように設計し、コメントを書くまでもなく、コメントに書きたい内容そのものがコードになっている形を目指すのです。
そうすると、最終的に詳細レベルの実処理部が「コードを読まないと分からない」状態で残りますが、それはコメントで読むべきではなくコード内容を読むべき箇所です。
「処理にコメントを書きたい」という気持ちは、「処理に名前を付けたい」と読み替えることができるので、それらを全て関数に切り出して名前を付ければ目的は達成できます。
「コードを読めば分かる」部分に名前が付けられていないのは、プログラマーの怠慢です。
もしコードの内容を説明するインラインコメントを書いていたら、今すぐ消して、それらを関数名にエンコードしてください。
一方で、Why や Note、Limitation などはよく書きます。
「そのような実装にした・しなければならなかった理由」はコード上には表現できないからです。
ざっくりと、第三者としてコードレビューを行う想定で、指摘や質問をしたくなるかもと一瞬でも思った箇所はコメントが必要な箇所だと思っておけば良いです。
#6
総合スコア122
投稿2026/01/05 07:02
編集2026/01/05 07:02Whyを残すのは大事だと思いつつ、実はコメント自体あまり書きたくない派です。
というのも、コメントも書いた瞬間から管理対象になってしまうんですよね。
以前関わったプロジェクトで、こんなコメントがずっと残ってました：
// 旧決済システム（PaymentV1）との互換性のため、この順序で処理する必要あり
…PaymentV1、3年前に廃止されてるんですけど。コードは動くから誰も触らない、でもコメントだけが残り続ける。こういうの、わりとあるあるじゃないでしょうか。
そこで最近は、Whyはプルリクエストに残す方向の方がいいんじゃないかと考えています。ADR的に、なぜこの実装にしたかという意思決定のスナップショットをPRの説明に書いておくスタイルです。
PRなんていちいち見に行くの面倒では？と思われるかもしれませんが、今はAIに関連する過去のPRを洗い出してもらえる時代になりました。
コード内のコメントより、PRという正式な記録に残しておく方が、経緯もレビュー時の議論も追えて良いかなと感じています。
#7
総合スコア200
投稿2026/01/05 09:01
[補足]
これの元の意図は「コメントを書くな」ではなく「コードを読みやすくしろ」で、元ネタは「冗長で説明的なメソッドはコメントよりも良い」（うろ覚え）だと思います。
で、そのメリットとして「保守されないコメント」は排除出来るし裏を返せば「メソッド名でwhyは表しようがない」になります。
#8
総合スコア11092
投稿2026/01/05 13:23
「コードを読めばわかるコメント」は本当に不要？ あなたのコメント流儀を教えてください！
コメントがいらないくらいきれいなコードばかりだったら良いのですが。コメントとコードを合わせて何とか解読できるようなコードもあるのである程度のコメントは書いてほしい派です。
自分は自分用であればあまりコメントは書かないですが他人と共有するものは書くようにしています。私の書き方が分かりにくい可能性もありますし、自分の書き方のクセも変わったりするので未来の自分のためにも書いておいた方が良いとは思っています。
#9
総合スコア68
投稿2026/01/05 23:23
編集2026/01/07 08:33所感
「コメント」を全部一緒くたにしているのがまず混線の元な気がしますね。
「Docコメント」と「それ以外」に分けないと収拾がつかないかと。
Docコメント
What と (意味論としての)How を書く場所。呼び出し側との契約。
ここでのHowは詳細実装のことではなく観測可能な振る舞いのこと。
- そのルーチンが何をするかを書く(what)
- そのルーチンが入力に対してどのような観測可能な加工をするかを書く(How)
- 何を入力として受け取るかを書く(what)
- 何を出力として返すかを書く(what)
その他のコメント
- why を書く
- What や How がないと理解できないルーチンは抽象度が足りない
- そのような抽象度が足りない処理はサブルーチンに切り出して適切な名前とDocコメントをつける。コメントに頼らない。
結果として
- Docコメント以外ではWhy以外を書く必要がなくなる
- メインルーチンは自然言語に近い感覚で読み下しできる抽象ルーチンの集合になる。結果としてWhy以外のコメントは不要
自分の結論
「名前とDocコメントの入出力仕様でやっていることが分かる」が100%達成できているコードベースでは、「その他のコメント」ではWhy以外不要
現実論として
この結論は、上記の整理が徹底できている理想的なコードベースでの話。実際の案件、特にレガシーでは、、、(ry
蛇足
あとどこに入れてもうまくまとまらなかったけど、感想として思ったこと。
- 価値の高いコメント/価値の低いコメント
- 必要なコメント/不要なコメント
は同値ではないと思います。
#10
総合スコア86553
投稿2026/01/06 02:53
「仕様」や「何故」とかじゃなくて、「どういう処理をしているのか」に関しては、tamotoさんがお書きのように、「読めばわかるコード」を書くのが原則でしょう。以下、その範囲の話です。
「コードを読めばわかるコメント」は本当に不要？
の回答は自明で、「コードを読めばコメントなしでわかる」が真なら、そのコメントは不要でしょう。不要なコメントは邪魔なので書いてはいけない(ノイズになる)。見つけ次第削除する。
問題は、
・読めばわかるコードを書ける人もいるけど、書けない人もいる
・読めばわかるコードは普通は読めばわかるんだけど、それを読んでも分からない人もたまにいる
というところで、説明能力・読解能力が足りない人が少なからず混じっている状況でどうするか？ということかと思います。前者はレビューして直させればいいんだけど、労力と時間がかかります。レビュー受けて書き直すことで本人が成長して書けるようになればいいんですが、それにも期間がかかりそう。
「初心者への優しさでWhat（何）も書く」
エディターの「初心者」ボタンを押したときだけ見えるように書けるなら、それもありかと思いますが、普通は邪魔ですね。
また、「~~という関数を知らないかもしれないのでコメントで説明を書いておく」は、初心者読み手がその関数を知らなければ、自分で調べて学ぶはずで、コメントでわかった気にさせるのはその学ぶチャンスを奪っていることになるかもしれません。まあ、「こんな関数は今後はまず使うことはないはずなので、学ばなくていい」とまで思うならそれもありですが。
#11
総合スコア1749
投稿2026/01/06 17:21
編集2026/01/07 22:43(念のため確認ですが、これって仕事で書くソースで、ソース中に「/**/」とか「//」とか「#」とかで書くコメントの話ですよね。)
私が数多くの現場を渡り歩いてきた経験から言うと、コメントに愚痴・独り言・ぼやき・いいわけ・他メンバーの批判・ポエム等を書くのはご法度でした。
そんなソースをコミットしたら、レビュー前に注意されるか注意します。
他のプログラマーのコーディングに問題があれば、コメント経由で注意するのではなく、別の手段で伝えます。
- ベンチャーか、普通の会社か
- 自社で完結しているソースか、最終的に他社に納品するソースか
によっても違うかもしれません。私は後者の現場が多かったです。
(追記)
本題について。
昔から「コードを読めばわかるコメント」は不要と言われるのは
// 変数aに3を代入 a = 3;
上記のことで、その関数が何をやっているか(関数ヘッダーコメント)、関数の中で処理の固まりに対して何をやっているかは、当然のように書きます(そこに個人の感情を入れないのは前述の通り)。
そのソースをレビューする人やメンテナンスする人の、言語や仕様に対する理解のレベルは個人差があるからです。
スキルが高い人、あるいは何カ月か後の自分自身だって、日本語で一言二言書いてあったほうが理解が早いでしょう。
「読めばわかるのだから書かない」を突き詰めると、コメントが全く無いソースが理想的ということになりますが、仕事の成果物としてはナンセンスですね。
#12
総合スコア407
投稿2026/01/07 08:08
編集2026/01/07 08:2620年近く業界に居る者です。
個人的にですが 、
書くべき
と思っています。
流石に全Stepに書けというのは異常だと思いますが、
処理まとまりのブロック毎に、
- どんなこと(目的)を
- どう(処理)するために
- どう(アプローチ/実現)しているか
といった説明は書いておいたほうが安全であるし、
可読性/保守性が上がると思うためです。
また、過去に参画したプロジェクトで散見されたデグレードなどから、
設計は合っているのに、実装が間違っている
ということをも間々見受けられ、レビューすり抜けも見てきたので、
設計書に記載の日本語を最初にコメントに打ち込んでおき、
それをもとに実装する
という概念も安全考慮上有効だったため、当たり前なことも必要と考える範囲で明記すべきだと思います。
他にも、
if (true == flagX)
などの場合、
flagXが何を指し示しているかはコード辿らないと分からないし、
引数で渡されている場合、本当に意図したものが渡されてるかも分からないし、
やはり可読性の面では
flagX(設定の〇〇)がtrue(利用可)となっている場合
など補記すべきかなと思っています。
変数名もっと分かりやすくしろよってのでも良いと思いますが、派生開発でflag乱立とか見たこともあるので、
変数名信じるなってのもある気がします。。。
総じて、PG/SEがみんな自分と同じ読解力/設計思想/概念知識(FWやデザインパターン)を持ち合わせているわけではないので、
デファクトかどうかは関係なく、コメント推奨派です。
#13
総合スコア366
投稿2026/01/22 03:26
個人的には、自分が忘れた頃に読んでも勘違いを起こすようなコメントは書かない。
「コードを読めばわかる」の内容が、全員同じではないので難しいと思うのです。
その読めるって判断も、まず、自分や他人がどのレベルまでコードが読めてるかがわからない。
読めているのか確認しよとしても、たとえ同じレベルでコードが読めたとしても、人によって「読めます」と「よくわからない」と答える人がいる。
あなたの回答
tips
プレビュー