はじめに
ただひとつ残ったものを手放さないために、nikkieです。
SpeechRecognitionのメンテナでの経験と直近のミノ駆動本_読書py1予習が結び付きました。
コメントアウトについてアウトプットします。
目次
- はじめに
- 目次
- print関数のために、意図しない出力がある
- 余計なprint関数はコメントアウト？ それとも削除？
- Uncle Bobも言ってる。「コメントアウトは絶対にやめましょう」
- コメントアウトは、削除するプルリクエストを作るチャンス！
- 終わりに
print関数のために、意図しない出力がある
SpeechRecognitionの過去のPR#434は機能追加のメリットだけでなく、将来の開発への小さなツケ2をいくつか含んでいたようです3。
Fixed IBM call to use api key. by chrisspen · Pull Request #434 · Uberi/speech_recognition · GitHub
PR#434がもたらしたツケの1つがprint関数による出力。
こちらについて、意図しない出力があるという内容のIssueが起票されました。
Recognize_google method not working as intended, solution provided here · Issue #645 · Uberi/speech_recognition · GitHub
これに関するプルリクエストを（複数）送っていただいたのですが（多謝）、それ（ら）を見て私は仰天しました4。
余計なprint関数はコメントアウト？ それとも削除？
以下のプルリクエストについてやり取りをし、最終的には（削除する変更を）マージしています。
Thank you for your pull request!
当初のプルリクエストはprint関数呼び出しの行のコメントアウトでした。
「コメントアウトより削除するのが望ましいと考えます」とフィードバックしています。
コメントアウトした理由も分かったのですが、ここでもPR#434のツケが絡んできている印象です。
print関数がコメントアウトされている行があり、それがこのプロジェクトのやり方なのかとならったとのこと5。
なるほど、ミノ駆動本でも近い話題がありましたね（15.3.2 レガシーコードに人は引きずられやすい）
結果的にprint関数はコメントアウトされているものも合わせて削除していただき、コードベースが小さく改善されました！
Issueを挙げてくださったり、プルリクエストを送ってくださったり、皆さまありがとうございました🙌
Thank you for all your contributions to improve SpeechRecognition's codebase.
Uncle Bobも言ってる。「コメントアウトは絶対にやめましょう」
直近で読んだ『Clean Code』の4章に、よくないコメントの一例としてコメントアウトがありました。
私の意見ですが、コメントアウトはデバッグテクニックだと思います。
意図したとおりに動かないコードに対して、どこまでは動くのか、原因を切り分けるためにコメントアウトは非常に有効と感じます。
ですが、デバッグを終えて動くコードが手に入ったら、コメントアウトにはコメントとして残す価値はないと考えます。
『Clean Code』4章を読んで「コメントは最小限。書くのであれば、十分な時間をかけて、最善のコメントを」と理解しました。
この理解に照らすと、コメントアウトはコードに残すべきコメントにはなりえない、なので削除すべきと考えます。
コメントアウトは、削除するプルリクエストを作るチャンス！
この記事を読んでいる方がここまでの主張に同意されるのでしたら、1つ伝えたいことがあります（考え方は色々あっていいと思っていて、同意できない方は引き返していただいてかまいません）。
OSSのコードにコメントアウトを見つけたら、それを削除するプルリクエストを送ってみてはいかがでしょうか？
削除する理由は、上で『Clean Code』を引いて示したとおりです。
「そんなこと私がやらなくてもメンテナの誰かがやってくれるでしょ」と思われるかもしれませんね。
ですが、SpeechRecognitionを例にすると、私（アクティブなメンテナ）の手が回っていません！（本人が1日1エントリとかで忙しい上に、めっちゃIssue来るよ！）
「直したいと思いつつも手数が足りない」、そんなときに送っていただけるプルリクエストはとても素晴らしくありがたいものなのです。
コメントアウトを削除するだけなら、以前紹介したブラウザからプルリクエストを作る方法が使えると思います！
終わりに
コメントアウトにまつわるメンテナ経験と書籍で得た知見からアウトプットしました。
コメントアウトもtypoと同じくプルリクチャンスだと思います。
気付いた方が小さなプルリクエストを送ってみるきっかけになったらとても嬉しいです。
私一人では手数が足りていないですが、プルリクエストを送ってくださる他の開発者の力を借りてOSSは開発できるんだなという気付きがありました。
Issue立てたら「プルリク作ってくれたらマージするよ」と言われたという話を過去に耳にしたのですが、そう言いたくなる心境、やってみると分かります。
他の開発者のプルリクが送られやすくなるようにメンテナが動くことができそうですが、具体的にはどうやればいいんでしょう？ 試行錯誤ですね（3月のYAPCでメンテナの先輩方に聞いてみよう！）
- 2/10(金)開催、コメントの章を読みます↩
- ツケの1つとその解消は メンテナ記 | setup.py中のnameを変えたらいかんぜよ - nikkie-ftnextの日記 で取り上げました↩
- このプルリクエスト、1つで複数のことをやろうとしていて大きすぎるように見受けられます。どんな物事にもメリット・デメリット両面があると思いますが、メンテする立場からは、このプルリクはメリット（機能追加）もデメリット（残されたツケ）も同量だけあるように感じてしまいます。当時マージする判断や事情もあったはずでそれは尊重したいと思いますが、いま目の前に積まれたツケもちょっとずつでも解決していきたいなと思っています↩
- なぜコメントアウトというやり方に至ったのかが分からず、私なら絶対やらないやり方で複数提案いただいたことで、かなりのショック（ダメージ）を受けました（あれ、私が間違っている？）↩
- https://github.com/Uberi/speech_recognition/pull/651#issuecomment-1380516382↩
