コメントの量に関して

Question

答えの無い質問となってしまいますが
開発の際どれくらいコメントを残してますか？

個人的にはソースコードから読み取れない処理に関してはコメントを入れるべきだと思いますがそれ以外はメソッド名や変数名の付け方で頑張った方いいと思ってます。
しかし、私のチームでは全てのメソッドにコメントを付けることが義務付けられています。
CakePHPでいうところのAction名にもコメントを付けるように言われているのですがどう思いますか？

できればコメントを極力書かない習慣にしたいのですが、説得させる情報が無いため色々とご教授いただけますでしょうか。

Comments

[yambejp]

「できればコメントを極力書かない習慣」にしたい理由はなんでしょか？めんどくさい？ご自身は他人のコメントをみることはなかったり、見ても意味がわからなかったりするのでしょうか？他人の書いたコードなんてコメント無しでみるのはそうとう苦痛だと思いますが・・・、いずれにしろチームでやる以上ドキュメントは残すのでしょうから、そとに残しているならソースに埋め込む必要はないような気はしますが

[ERINGI5]

コメントを書く事が面倒だとか、手間がかかるとは思っておりません。コメントが書ける事によって変数名の意味や価値が薄れてしまう事を懸念しています。(書く人によりますが....)変数名を見ただけで何が代入されているか特定でき、メソッド名を見るだけで中の処理が把握できる方がベストだと思っておりました。（みなさんの意見を参考に過去形にさせていただきます。）変数名を付けるのにだいぶ悩んでいるので逆に生産性は下がっているかもしれません.........

Answer 1

仰るように基本的にwhy not以外書く必要はありません。
whyは不要、コード読めの精神ですね。

全てのメソッドにコメントを付ける

所謂PHPDocですね。
ツール通せばドキュメントが出来上がるので、SIerの現場等では徹底しておけばそれはそれで結構でかいメリットがあります。

他にもPHPStormではパラメータでクラスを指定しておくと、
クラスメソッドの補完が効きますし定義に飛べるようになり開発が楽になります。

まぁPHPDoc書く時はざっくりとした概要の紹介だけで十分です。
書きすぎるとメンテする時にコメントとコードを二重でメンテするはめになるので詳細は書かない方が良いでしょう。
詳細書きたければ単体のテストコードに時間掛けたほうが良いと思います。

Comments

[miyabi-sun]

https://twitter.com/t_wada/status/904916106153828352
テスト駆動開発の書籍でおなじみの和田氏のツイートを紹介

> コードには How
> テストコードには What
> コミットログには Why
> コードコメントには Why not
> を書こうという話をした

[miyabi-sun]

質問文の状況に於ける私の考えとしては、
前提の「なんでPHPDocを書かなきゃいけないの？メンバーがIDEで利用したり、ドキュメントにして客に出してるの？」辺りはチームで確認とっても良いとは思います。
その結果、チームの判断がメリットがデカイからPHPDocを残すと決定したのであれば従うべきでしょう。

Answer 2

できればコメントを極力書かない習慣にしたい

コメント不要論には、何か根底に誤解がある気がします。
コメントが減るのは結果であって、減らすのが目的ではないです。

もし、交通事故の多い場所に、「この先急カーブ」とか看板が多いとして、
たんに看板をなくしても、事故は減りません。むしろ増えるでしょう。
あるいは、咳を我慢したら風邪が治るか、ということです。

だから、リファクタリングなどによって、コメントの必要がなくなり、
結果的に減るのは良いです。コメントだけ消してもダメです。

しかしここで、現実問題として、リファクタリングする時間がないことも多く、
それならせめてコメントを残しておいてくれれば、
問題を探す時間や、うかつに変更して出たバグを潰す時間の浪費を避けられます。

コメントを書くのは多くの場合で最善ではないですが、基本的に善です。
コメント自体は、根本的解決でなく、対処療法的な手段ですが、
たんにそれを書かないのもまた、表面的な解決に過ぎません。

---

メソッド名や変数名の付け方で頑張った方いいと思ってます

それでもコメントにまだ抵抗があるとしたら、こう考えてください。

コメントは最終結果ではなく、リファクタリングの過程だと考えます。

何か難しい、分かりにくい、問題のある処理があったときに、
最初はまずコメントを書いてみる。実装コストが安いので気軽に試せます。

根本的な問題があると思った場合、コメントのままにせず、
さらに、説明的な変数にする、メソッドに切り出す、クラスに分ける、
ライブラリ化する……などと、より大きな単位にしていく場合があります。

つまり、コメントを書かないというより、コメントを書いて、
さらに大きな単位でまとめられないかを考えます。

これを最初から大きな単位で書くと、
不要なものを作ってしまいがちです。

コメント自体を書かないことが大事というより、
コメントから先を書くことが大事だと思います。

---

Comments

[ERINGI5]

「コメントは最終結果ではなく、リファクタリングの過程」なるほど.......
納得できる考え方ですね。

ご指摘いただいた通り、現状はただコメントをなくすだけで可読性の悪いソースになっている気がします。
あくまでリファクタリングの過程と言う考え方で徐々にいいコードにできればと思います。

ご教授ありがとうございます。

[miyabi-sun]

「テスト駆動開発」という書籍があります。
この書籍ではテストを先に書けと説いています。
丁度LLmanさんが本回答で説いているコメントと同じ箇所に当てはまります。

コメントの場合、機能を実装が進むにつれ、重複の整理の為に削られる運命にありますが、
テストコードは整頓されて多少削られる可能性はありますが、その場に全部残ります。
（当然、テストコードの側は死ぬ気でメンテするコストも必要で、「テスト駆動開発」の本の実践をチーム全体でどこまで受け入れられるかだと思います。）

このようにプロジェクト全体で何を何処に書くかを担保出来れば良いので、
後はチーム全体でコメントとどう付き合っていくかだけの問題に尽きるでしょう。

[LLman]

＞ERINGI5さん
＞リファクタリングの過程と言う考え方で徐々にいいコードにできれば
そうですね。コメントというと、古いスタイルに思えるかもしれませんが、
じつは、アジャイルのように反復的な開発スタイルと相性が良いと思います。

＞miyabi-sunさん
＞「テスト駆動開発」
そうですね、テストと似たところがあります。
テストも「コメントから先」にあるものです。

テストは重要です。が、コストが高いので、100％カバーするのが理想でも、
現実的には、いかに重要な部分をカバーするか、という問題になりがちです。

日本語の問題もあります。日本人には日本語のコストが低いので、
日本語コメントだと、思考しやすい、注意しやすい面もあります。

だから、つまりこうです。100％テストが書いてあって、
コメント0％というのが、コメント不要論者が想定する理想状態です。
でも、現実的にはそこまでする開発リソースが足りない場合も多い。

それなら、とりあえずコメントを種のようにバラまいておいて、
リファクタするなり、テストを書くなり、そこから育てていく
きっかけにするのも、現実的な選択肢としてアリだと私は思ってます。

Answer 3

引数の意味や返り値など、どんなメソッドでも必要になるようなものを書くPHPDocという記法がありますので、義務付けられているのであればそれに従って書くのが最適解かと思います。

PHPStormやNetBeansなど、PHPに対応したIDEの場合、PHPDocから情報を読み取って、メソッド呼び出しのところでポップアップ表示したりというような機能があります。

Answer 4

コメントに関しては、つける派とつけない派にどうしてもわかれますね。
私はつける派です。
コメントの付け方やつける理由は以下の通り。

• 当たり前のことは書かない。aに1を代入する、とか。

aに1を代入するということは、つまりどういうことかを書く。

• コードを読めばわかる単純な処理でも書く。

ある程度の処理単位でコメントを入れることで、大まかなブロックができるので、可読性が上がります。

• 他人が見たときにわかりやすい。

自分が書いたコードなんて他人には即座に理解できないものです。

• 時間が経ってから自分が見てもわかりやすい。

例え自分がわかりやすく書いたコードでも、時間が経つと忘れているものです。

• コメントがなくて文句を言う人がいても、コメントがあって文句を言う人はいない。

仕事としてコードを書くなら当然お客さんがいるわけですから、納品物として文句を言わせないためにもコメントは必須。

Answer 5

個人でやっている場合にはほぼ残さないですね。
ERINGI5さんがおっしゃっている程度で十分だと思います。

どこまで書く書かないという判断はそのプロジェクトによって違うと思います。
結局最終的な目的にすべきなのは生産性ではないでしょうか。

コメントを書くことで生産性が下がるなら要らない。
コメントを書くことで生産性が上がるなら書くべきだと思います。

それは個人の生産性ではなく、今だけの生産性ではなく、製造の生産性だけではなく
プロジェクト全体・納品・管理・今後の保守・運用も含めた全てを加味した上での生産性です。

基本的にはプロジェクトが大きければ大きいほど、長ければ長いほど、コメントは重要になって来ると思います。
（コーディング規約やコメントルールを守るためのコストもかかって来ますが・・・）
小さくて短いプロジェクトなら恐らく書くのは無駄です。

プロジェクトによっては納品や管理に使われている場合もありますので
１人や数人の製造コストだけを見て判断すべきものではないと思います。

全てを鑑みてもコメントを書くコストが無駄ならば、やめるべきだと思います。

が、それでも政治的なものやルールを変えるためのハードルやコストなどもありますので
トータルで考えると、プロジェクト途中でルールを変えるのはあまり得策だとは思いません。
（小さいプロジェクトならできるかもしれませんが。）

新しくプロジェクトが立ち上がる時に考えるべきことなのかなとは思います。

Answer 6

コードドキュメンタ（コード内のコメントをもとに、コード解析結果をドキュメント化するツール）のために書くコメントというのもありますので、一概にはコメントの量を云々は言えません。
JavaDoc や PHPDoc は、こういうドキュメント化のためのコメントです。

その意味では、CakePHPにおけるActionにもつけることは必要だといえるでしょう。それはすなわち、Action一覧を作る際の資料になるものだからです。

メソッドの in/out 、概要を明示するコメントは必要でしょうが、メソッド内部のロジックに絡む部分まで細かくコメントを入れるかといえば、それは入れないほうが良いでしょう。コードを読む際に補助となる程度があればよいかと思います。
例えば if 分岐で、「なぜこのif判定になるのか」を書いておくなどです。機能の詳細設計と見比べたときに、正しい if 判定をしているのかどうかわかりやすくなりますし。

Answer 7

ソースコードは今後誰が読むのかわからないものですから, コメントが多いに越したことはないと思います. どうせ後から消すことも出来ますし.
それよりも「量を減らす」のではなく「質を上げる」ほうが重要であろうかと. コメントの履歴が残るような管理は絶対にやめるべきですが, コーダーさんの意図を正確に後世に伝える目的であれば積極的に記述して良いかと思います.

Answer 8

私もPHPStormを使っており、PHPDocの記述もあったのでコメントはその為っぽいです。
PHPDocがあまり理解出来ておりませんでしたのでこれを機に少し調べてみようと思います。

ご回答ありがとうございました。