【ポエム】プログラムのコメント書く書かないについて

書く書かないの二択の問題じゃないです。
リーダブルコード読んで適切なコメントを書きましょう（適切でないコメントは書いてはいけない https://t.co/i732OlBFsX

— ダイスケ＠日常アカウント (@moyashidaisuke) 2019年11月2日

これの補足です。

書き始めたら私の10年ちょいのエンジニア経験と、勉強してきた事が割と詰まった感じになりました。

チームで取り組もう

複数人での開発を想定していますが、個人開発の場合でも先月の自分は他人なので気にした方が良いでしょう。

まずはルールを守ろう

まず優先なのはチームのルールです。

• プロジェクト、会社にコーディング規約として明記されているか？
• 明記されていなくても暗黙的なルールはあるか？
  • レビューでの指摘事項を眺める
  • コードをざっと眺めてみる
  • 現場の先輩に聞いてみる

まず上記を確認しましょう。

どんなにうんこ💩なルール（とあなたが思う）だとしても、もしルールがあるのであれば、まずはルールに従う事をおすすめします。あなたの考えとは違うかもしれませんが、そのルールになっているのには何かしらの理由があります。

また、他の人が書いたコードと規約をそろえる事で、プロジェクト全体のメンテ性を保つというのはとても大事な事です。あなた一人がそれをやぶろうとしても結局レビューでNGになるかもしれませんし、仮にレビューが通ったとしてもそれまでメンバーが心血を注いできた環境をあなたが壊す事になります。

あなた一人くらい、と思うかもしれませんが、割れた窓を放置してはいけません。あなた一人が規約をやぶると、みんなが破り始めます。あなたはそんな戦犯になってはいけません。

※割れ窓理論が気になる方は達人プログラマーを読みましょう www.s-arcana.co.jp

新装版 達人プログラマー 職人から名匠への道

もし今のルール（規約）がks💩だと思うなら、そのルールを変更しようとするのは悪い事ではありません。が、変更には適切なプロセスをもってなされるべきです。

前述の通り、その規約には何かしらの理由があるはずです。その必然性が納得行くものかどうか、チームとして取り組むべきです。

ルールを変えよう

もし今のルールが著しくチームの生産性を下げていて、価値を提供する事の邪魔になっているのであれば、変更を検討しましょう。

イソップ童話の1番目のレンガ職人のように、それがルールだから、と考える事を放棄してはいけません。機械的に言われた事を受け入れてそのまま取り組むのは、優れたプログラマーのする事ではありません。

www.total-engagement.jp

コードと同じように、ルールも何もしないと品質が劣化していきます。継続的にリファクタしていくべきでしょう。当時は有効であったルールも、現在はかえって足かせになっているかもしれません。

が、この時気をつけないといけないのは、「ぼくがかんがえたさいきょうのこめんとるーる」をみんなに強要するような姿勢をとってはいけない、という事です。

• そのルールを考えた人
• そのルールを守る事に労力を割いてきた人

この先輩たちを貶めるような態度を取ってはいけません。

どんな正しい変更であっても、変更を受け入れて実践するにはエネルギーが必要です。チームとして取り組む課題である以上、彼らにも協力してもらえるように話をしないと、チーム内で軋轢を生むだけになるでしょう。

人を動かす 文庫版

コメントのルールの決め方

では幸いにもコメントのルールを決められる、たたき台を考えられる環境に身を置けた場合、以下のような事に気をつけましょう。

コメントを書く目的を明確にする

コメントを書くのだって無料ではなく、貴重な工数を使って書く事になるので、なんのために書くのか、という目的は明確にした方が良いでしょう。

そんなのするまでもないぜ！と思うかもしれないが、意外と人によって考え方は違うものです。

またエンジニアリングに理解が無いマネージャーから「動作に関係ない事に工数はかけてはいけない」というありがたいご通達が来ても困らないように、コメントを書く事がどうしてプロジェクトのためになるのか、というのは明確にしておいて損はありません。

よくある大きな目的は以下にようなものでしょう。

• コードの可読性を高める
  • 自分以外が担当した機能でもスムーズに取り掛かる事ができる
  • なのでチーム全体の生産性が上がる
  • 半年後の自分はコードの大半を忘れているので、やはり可読性に対する考慮は必要である

場合によってはコメントの行数で水増しする事によって納品物の水増しをして利益になっているかもしれませんし、バージョン管理を（GitやSVN等）を導入していないので、「誰がいつ何のために変更したのか」「このコードの所有者は誰なのか」を書いて管理するのも目的になるかもしれません。

※今どきバージョン管理を使わないなんてありえないと思う方もいるかもしれませんが、そんな事はありません。現にこのブログのcssはバージョン管理をする事ができません

世の中の標準を基準にする

一般的なルールに従う事は大きなメリットがあります。新規参画したメンバーが独自ルールにつまずいて開発のスタートに躓く事は減るでしょうし、そもそも標準のルールには標準になっただけの理由があります。

ある程度メジャーな言語であれば、誰が考えたコーディングルールを参考にしましょう。例えばJavaScriptであれば下記のリンクが参考になります。 qiita.com

使用しているフレームワークやライブラリのスタイルも参考になるでしょう。

また、javadocのようなドキュメンテーションツールの使用も検討するべきです。ツールに対応するフォーマットで記述していくだけで、全体的にそれなりのルール管理化に置かれる事でしょう。

また、以下の書籍も参考になるでしょう。

リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック (Theory in practice)

Clean Code アジャイルソフトウェア達人の技

メンバーとの相互理解を深める

コメントに関する考えは人それぞれです。またソースコードを読む人の技術レベルによって、「それはコードを読めば明白だからいらないでしょ」の基準が異なったりします。

あまり細かく決めすぎると窮屈になってしまいますので注意しつつ、どんな内容が有用なコメントなのか、という議論をメンバーとしましょう。（ここでもメンバーへのリスペクトは忘れずに）

Team Geek ―Googleのギークたちはいかにしてチームを作るのか

私のコメントの書き方についての考え方

と、ここまでコメントに対する取り組み方を述べてきましたが、ここからは私の考え方を述べます。 前提条件が無い、自分一人のプロジェクトの場合は以下のルールにする事が多いですが、プロジェクトやチームメンバーの好みによって、何が正しいかというのは左右されます。あくまで参考として。

コメントはできるだけ書かない

コメントは最終手段とします。なぜなら、コメントがただしいかどうかをテストする方法は無いからです。つまり、コードに比べると、コメントというのは著しくメンテ性が悪いという事です。

コメントを書いた時は正しかった事でも、仕様変更によって内容が古くなるかもしれません。それを検知する方法は関係ありそうなキーワードで全文をgrepして検索するか、たまたま目についた時に気がつくくらいしかありません。

動作確認をしたり、テストコードを書いたりという事ができないのです。

矛盾しているようですが、不必要なコメントを書く事は、メンテ性の悪化を招きます。

だから、コメントはできるだけ書かないべきです。（必要なコメントを書くなと言っているわけではありません）

できるだけツールを使う

xDocや、lint等のツールを使って、ルールの強制や書き方を自動化/定型化できないか検討します。 レビューで「ここはこのルールに従ってないよ」と指摘するのは、言う人も言われる人も多かれ少なかれエネルギーを消費します。面倒なことは機械にまかせましょう。

また、Git等のバージョン管理を使えば、変更日時や変更者のコメントは不要になります。例えばこんなのです。（SIer時代はこういうのいっぱい見ました、、今はどうなんでしょうか

/**
2019/01/01 moyashidaisuke 案件番号XXXのため変更 start
*/
〜〜省略
/**
2019/01/01 moyashidaisuke 案件番号XXXのため変更 end
*/

世の中の標準を基準にする

前述の通りです。よっぽどエッジの効いた環境で無い限り、あなたが考えたルールは既に誰かが通った道です。車輪の再発明はやめて、あなたにしかできない事にエネルギーをそそぎましょう。

参考になりそうな標準ルールやコードを探してきて、ちょっと修正しておしまいです。もしその標準ルールに納得できないのであれば、チームメンバーでその規約や書籍についての勉強会を開くと、ついでに理解が深まって良いかもしれません。

まとめ

なんか口調が強くなってオライリーの翻訳本みたいになってしまいましたが、深い意味は無いです。私がそう思っているだけなので、今すぐみんなこれに従え〜とかじゃないです。私はこうだよ〜とかコメントいただけるとうれしいです。