IT

プログラムにコメント書かない文化もあるよって話

以下の記事を読んで。

530000micro.hatenablog.com

僕が勤めている会社では、原則、プログラムにコメントを書かないのがルールです。

人生で初めてプログラムに触れてからこのかた、プログラムには必ずコメントを書けと指導されて来ましたし、自分自身も、後輩たちにちゃんとコメント書けよと言い聞かせてきました。そんなわけで、最初に全然コメントのないソースコードの山を見たときは、正直「ゲッ、なんじゃこりゃ……」と面食らったのは確かです。

ところが、「なぜうちのプログラムにはコメントがないのか?」と同僚に尋ねてみると、実に納得の行く回答が返ってきたのでした。

Contents

なぜコメントが必要なプログラムを書くのか?

同僚いわく、「コメントが無くても読めるようなプログラムを書け」という思想が根底にあるのだそう。

適切に関数や変数が命名され、スコープがきちんと管理され、ロジックの流れが整理されているコードならば、わざわざコメントを書く必要はない。逆に言えば、処理をプログラムできれいに表現できていないからこそ、コメントが必要になってしまう。だから、うちの会社のプログラムにはコメントが無いんだよ。と、そう教えてくれました。

なるほど確かに。よく、コメントは未来の自分に向けて書くものだ、と言われます。自分の書いたプログラムを一ヶ月後に見ると、なぜこんな処理を書いたのか思い出せないということがある。そうならないようにコメントを書いておくのだ、と。しかし、自分自身ですら書いた理由を思い出せないプログラムとは、それ自体欠陥があるように感じられます。

「おまじない」「これを消すとなぜかバグる」なども同様。プログラマたるもの、自分で説明できないコードは1行たりとも書いてはいけないと僕は考えます。これらのコメントは、自分自身が書いたプログラムに対する責任からの逃げでしかありません。おまじないと書くくらいなら、なぜその1行が必要なのか調べて理解すればよい。これを消すなと書く前に、消されるようなコードが重大なバグを引き起こす欠陥をつきとめ、修正するべきでしょう。

プログラムそのものの質を高めるために、コメントを禁止するという考え方には、一理あるように思えます。

コメントは余計なコストを生む

コメントのもう一つの弊害は、常にメンテナンスが必要になるという点です。

ロジックの妥当性であれば、自動ユニットテストを使えばある程度は担保できます。しかし、現行処理に対するコメントの妥当性は、機械ではチェックできません。結局、人力でのメンテナンスが必要になってしまうのですね。本来、コードを書くことに使われるべきプログラマのリソースが、コメントの管理に割かれてしまうのは、生産性の低下であると言えます。

また、メンテナンスの不備によってコメントが嘘になってしまうと、大きな負債になります。コメントにはAと書いてあるけど、実際の処理内容はBだ。これはコメントが間違っているのか? それともプログラムがバグっているのか? 関係者に問い合わせたりドキュメントをひっくり返したりと、余計な作業がどんどん発生してしまう。こうなってしまうと、コメント無いほうがよっぽどマシだったってことになっちゃいますね。

コメントを書かない練習をしてみよう

僕は今の会社に入社して以来、コメントを書かずにプログラムを書く修行をしておりまして、どれだけ可読性の高いコードを書けるかにはかなり敏感になりました。直感的に理解できる命名になっているか。処理の流れに不自然な部分はないか。無駄に条件分岐が増えすぎていないか。こういったことに、以前にもまして気を配るようになっています。

現在、コメントを書くのが当たり前の文化でプログラミングをしている方も、一度、コメントを書かない練習をしてみてはいかがでしょうか。今までよりも、もっとわかりやすい、簡潔なコードが書けるようになるかもしれませんよ。ではでは。

追記(2016/4/22)

まさかはてブ総合トップに載るとは思わなかった。言葉が足りなかった部分がありましたので、追記して補足します。

ブコメでも指摘を頂いた通り、プログラムで表現しきれない部分は、すべてコミットメッセージやコードレビューのログ、チケットへのコメントなどに書いています。コミットとコードレビューのログはチケットに紐付いており、相互参照が可能です。

結局コメント書いてるじゃんと思われるかもしれませんが、「なぜこの修正を行ったのか」「修正前後で動作がどう違うのか」などの情報は、プログラムそのものではなくコミットやチケットに付随する情報のため、プログラムのコメントとして残すのは不適切です。さらにいえば、プログラムのコメントはドキュメントとしての可読性に乏しいので、より詳しい情報を書こうとすればするほど読みにくくなります。ただのプレーンテキストなのですから当然です。それならば、文字の修飾、ファイル添付、ユーザIDのコールなどの機能が使えるチケットにコメントを書くほうが理にかなっているでしょう。

なおコードレビューに関しては、デベロッパー全員がレビュアーとしての役割を担っており、各チケットに関して複数人がレビュアーにアサインされます。結構これが厳しくて、なんてことないコードであっても、少しでも改善の余地があると判断されればリジェクト食らいます。

プログラムの仕様書にあたるドキュメントについては、詳細かつ簡潔(1チームにつき Word 数十ページ程度)にまとまったものが共有されており、仕様変更が発生した場合には随時メンテナンスが入っています。コーディング担当者がメンテを忘れても、レビュー時にたいてい誰かが指摘してくれるので、メンテナンス漏れが起きることは少ないです。

さらに、ソースのコミット後はサーバ上で自動コンパイル、自動テストが走る上、リリース前にも品質チェック部隊による最終テストが実施され、確実な動作を担保しています。

これら、製品の品質を守るための強固な仕組みがあってこそ、コメントを書かないという文化が実現可能なのだと思います。

ABOUT ME
はっしー
ニュージーランド在住の元プログラマ。 日本のIT企業で月100時間超えの残業を経験して過労死しかけたことをきっかけに国外脱出、毎日定時帰りの生活と年収アップを実現させる。脱社畜、英語、海外移住などをテーマに情報発信中。Twitterフォロワーは1万8千人以上。ニュージーランド永住権ホルダー。

POSTED COMMENT

  1. yonsamantha より:

    はげどう

  2. pekimoche より:

    一見正しい事を言ってるようにも見えるが、新しくやってきた人がコードを読み解けずにバグを生むリスクを増やすだけ とも思える。 コメントがいらないのはシンプルな仕様のみ。暗黙的な仕様はコードから読み解くのは不可能。

  3. asdfasfasd より:

    私はこの本読んでからコメント書くのやめました
    https://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882

  4. nowokay より:

    「メンテナンスの不備によってコメントが嘘になってしまうと、大きな負債になります」とあるけど、それは分離したドキュメントのほうがメンテナンスされなくなるし、大きな負債になりがちだと思います。
    一方で、メンテナンスが相対的に難しいドキュメントに対しては「コーディング担当者がメンテを忘れても、レビュー時にたいてい誰かが指摘してくれる」としているのに、コメントはメンテナンスの不備の可能性があるというのは、文章が不正確か、レビューのやり方がおかしいかどちらかに思えます。

  5. taka6285 より:

    よく新人が書くような、コード自体の説明のコメントは不要だと思います。
    コメントのメンテナンスが必要になるので、無い方がいいです。
    必要なのは、ソースからではわからない、なぜそうしたのかだとおもいます。
    変更履歴などは可読性を下げるだけなので、コミットコメントをしっかり書くことが、重要だと思ってます。

COMMENT

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です