元ネタこちら
プログラムにコメント書かない文化もあるよって話
http://nzmoyasystem.hatenablog.com/entry/no_comment_culture
http://megalodon.jp/2016-0422-0815-58/nzmoyasystem.hatenablog.com/entry/no_comment_culture (魚拓：ものすげぇ念の為)
まぁおいちゃんの結論は「コメントを書け！( http://d.hatena.ne.jp/gallu/20150328/p1 )」で片付くんだけど、そこに至るまでの諸々を、改めてざっくり考察。
筆者が勤めている会社では、原則、プログラムにコメントを書かないのがルールです。
まぁそれが「ルールである限り」、それはそれでよいのかなぁ、と。後先考えなければ。
同僚いわく、「コメントが無くても読めるようなプログラムを書け」という思想が根底にあるのだそう。
適切に関数や変数が命名され、スコープがきちんと管理され、ロジックの流れが整理されているコードならば、わざわざコメントを書く必要はない。逆に言えば、処理をプログラムできれいに表現できていないからこそ、コメントが必要になってしまう。だから、うちの会社のプログラムにはコメントが無いんだよ。と、そう教えてくれました。
これは…多分、エピさんが呟いてくださった内容に「全てが込められている」ような気もビシバシとするのですが。
https://twitter.com/epitwit/status/723306702678843392
んむ。それが”なに(what)" かはクラス名/関数名で、"どうやって(how)"はコードそのもので表現する。残るは"なぜ(why)"そうしたかだが、それをコメントに記すのであるよ。
ということ。
コードに書いてあるのは「どうやって」がメインだし、書いてあっても「それがなにか」まで(ちなみにwhatがめちゃくちゃなソースはそれはそれで死ぬるほど見たくないｗ)。
それの「なぜ」の部分を、どうやって「コメントが無くても読めるようなプログラムを書け」という言葉で賄うというのだろう？ 賄えるというのだろう？
しかし、自分自身ですら書いた理由を思い出せないプログラムとは、それ自体欠陥があるように感じられます。
この時点でアウトなのが。
「思い出せない」場合に欠陥がある、というお話。であるとすると「正しく思いだした」のか「歪んで思い出した」のか、そのあたりの差分はどうやったら判定可能なのだろうか？
「思い出す」って単語の時点で「記載されていない内容である」事はまず明白で、その時点で「以前の想定を正しく思い出せたのか」どうかなんて、誰が判断できる？
もう一つより重要なのは。業務で記述したソースコードは本質的に「ほかの誰かがメンテナンスをする可能性が常に想起される」事。
「あながたこう思って書いた」思い出を、あなた以外の他人がどうやって「思い出す」事ができるのざましょ？
このあたりからしても、正直「業務でのプログラミングなのか？」っていうのが、大変に色々と疑問。
コメントのもう一つの弊害は、常にメンテナンスが必要になるという点です。
この辺は「しろ」で終了。
そもそもコードを書く時って「先にコメント」書いたりしない？ 思考の流れの整理かねて。
また、メンテナンスの不備によってコメントが嘘になってしまうと、大きな負債になります。コメントにはAと書いてあるけど、実際の処理内容はBだ。これはコメントが間違っているのか？ それともプログラムがバグっているのか？ 関係者に問い合わせたりドキュメントをひっくり返したりと、余計な作業がどんどん発生してしまう。こうなってしまうと、コメント無いほうがよっぽどマシだったってことになっちゃいますね。
これも限りなくバイアスがかかっていて。
「コメントがなく、誤った処理が書かれていて、テストコードも誤っている」場合、同様に負債にしかなりません。
まぁ「じゃぁ、コメントとコードで違うことが書いてある、ことによって誤りが見つかりうる可能性がどれくらいあるか？」っていうとそれはそれで限りなく微妙ですしそれによって「二重防壁」とか考えるタイプではおいちゃんは全くないのですが。
ただ「メンテナンス不備によってコメントが嘘になることで負債になりうるからコメント不要」ってのは、明らかに「ちがうんでないかい？」と思う。
筆者は今の会社に入社して以来、コメントを書かずにプログラムを書く修行をしておりまして、どれだけ可読性の高いコードを書けるかにはかなり敏感になりました。直感的に理解できる命名になっているか。処理の流れに不自然な部分はないか。無駄に条件分岐が増えすぎていないか。こういったことに、以前にもまして気を配るようになっています。
「直感的に理解できる命名になっているか。処理の流れに不自然な部分はないか。無駄に条件分岐が増えすぎていないか。」なんてのは、コメントの有無に限らず「敏感に」ならにゃならんところなので、この辺も大変にもにょり。
ただ、もし「コメントがあるからいいやぁ」っていう感覚の技術者さんがいらっしゃるのであれば。「自分のプライベートなコードで」「秀作として」であれば、そーゆー訓練のしかたも「ありなのではないかなぁ？ もしかしたら」ってレベルではあります、が、その程度。
で、後出しの追記に突っ込み。
プログラムで表現しきれない部分は、すべてコミットメッセージやコードレビューのログ、チケットへのコメントなどに書いています。コミットとコードレビューのログはチケットに紐付いており、相互参照が可能です。
それを「コードに書いてはいけない」理由は？
結局コメント書いてるじゃんと思われるかもしれませんが、「なぜこの修正を行ったのか」「修正前後で動作がどう違うのか」などの情報は、プログラムそのものではなくコミットやチケットに付随する情報のため、プログラムのコメントとして残すのは不適切です。
「プログラムのコメントとして残すのは不適切です」という記述はあるけど、では「なぜ不適切なのか」が、未記述なので、今一つ。
ちなみにおいちゃんの切り分けとしては
・基本は可能な限りプログラムのコメントで
・「全体を通した経緯」とかは、別所にて(大体はチケットのコメント)
・「削除した」部分の削除理由などはコミットメッセージ
って感じです。
理由は簡単で。「ｎ個の本を行き来しながら読書するのと１冊の本を読書するのと、どっちが楽？」って考え方。
人間って本来的に「あちこちに移動しながら散らかると頭ん中もとっちらかる」ので、どこかに集約したいってぇのは、割と普通の事だと思うのです。
半可通は「あちこちの大量なものを一意に読み込めるオレ優秀！」とかなるみたいですが。
さらにいえば、プログラムのコメントはドキュメントとしての可読性に乏しいので、より詳しい情報を書こうとすればするほど読みにくくなります。ただのプレーンテキストなのですから当然です。それならば、文字の修飾、ファイル添付、ユーザIDのコールなどの機能が使えるチケットにコメントを書くほうが理にかなっているでしょう。
そもそも「plain textで書けない背景ってなによ？」とか思うのですが。
「文字の修飾」？ はぁ？ なんで必要なの？
「ファイル添付」これはまぁチケットだねぇ。だけどそれは「プログラムで要求されているコメント」とかぶるの？ それこそ「仕様書」レベルのお話ではなくて？
「ユーザIDのコール」ん…微妙にこれは意味が不明なので(あまりにも複数の事象が想起される)、ノーコメント。
プログラムの仕様書にあたるドキュメントについては、詳細かつ簡潔（1チームにつき Word 数十ページ程度）にまとまったものが共有されており、仕様変更が発生した場合には随時メンテナンスが入っています。コーディング担当者がメンテを忘れても、レビュー時にたいてい誰かが指摘してくれるので、メンテナンス漏れが起きることは少ないです。
仕様書にあたるドキュメントがWordであるってのは色々と突っ込みたいんだが、とりあえずそれは置いておくとして、状況としては「原則的には」割と好ましいと思う。
ただ「コーディング担当者がメンテを忘れても、レビュー時にたいてい誰かが指摘してくれるので、メンテナンス漏れが起きることは少ないです。」ってことは、あるんだよね？ ってのと。
まぁもちろんそれは「コメント書いたって漏れるときゃ漏れる」んだけど。
コードだと、コードレビューのタイミングで「…あれ？ コメントと処理内容食い違ってるぞ？」と一目でわかるので突っ込みやすいのだけど。ここの職場の方は全員「Wordとプログラムを常に交互に見比べている」んだろうか？ という疑問。
「常に交互に見比べている」んならよいのだけど、「時々見比べる」だと、時々以外のタイミングの時に「見つかるはずのメンテミスが見つからない可能性」って、ない？
さらに、ソースのコミット後はサーバ上で自動コンパイル、自動テストが走る上、リリース前にも品質チェック部隊による最終テストが実施され、確実な動作を担保しています。
この辺はコメントと全く無関係だよねぇ。
ちぃと興味深いんで改めてBlogを追いかけてみたんだけど…とりあえず今の所「まぁこんなもんかなぁ」くらいの雑感。
プログラムは「その大半が読まれる」ものなので、「出来るだけ読みやすい」ほうが全体としてはお仕事がはかどる可能性が高く。
かつ「読みやすさ」の中には閲覧性とかも含まれるので、今回のBlogの論調であれば「ならおいちゃんはコードにコメントを潤沢に書く」を選ぶかなぁ、とか思ってみたのでした。
あと。
なんで「リーダブルコード」の本が最後に紹介されているんだろ？
あの書籍、「コメント書け！ 書け！」ってがっつり書いてあるはずなのだがｗ
