こんにちは。AndroidアプリエンジニアのMoriです。
先日、私が執筆した『良いコードの道しるべ 変化に強いソフトウェアを作る原則と実践』の出版を記念して、俺達はなぜ良いコードを書くのか 〜『良いコードの道しるべ』著者と探る変化に強いソフトウェア〜というトークイベントを開催しました。
本イベントでは、本書の紹介を行った後、類書の執筆者・翻訳者の方々を招き「コードの保守性」をテーマにパネルディスカッションを実施しました。この記事では、そのディスカッションで交わされた内容をダイジェストでお届けします。
登壇者紹介
森 篤史 / (@at_sushi_at) / LINEヤフー
LINEヤフー株式会社所属、Androidアプリエンジニア。明石工業高等専門学校に入学後、プログラミングを学び始める。複数のプログラミングコンテストで受賞する一方、継続的な開発の難しさや大切さに気がつく。現在はコミュニケーションアプリ「LINE」のAndroid版の開発に携わる。2019年度未踏IT人材発掘・育成事業スーパークリエータ。
著書：『良いコードの道しるべ 変化に強いソフトウェアを作る原則と実践』
秋 勇紀 / (@___freddi___） / LINEヤフー
「翻訳した本が多すぎてもう内容覚えてないよ...」と言いながら、翻訳した本関連で呼び出される人。助けてください。LINEヤフー株式会社所属のエンジニア。
翻訳書: 『Good Code, Bad Code ～持続可能な開発のためのソフトウェアエンジニア的思考』 他
高田 新山 / (@stzn3）/ LINEヤフー
異業種からソフトウェアエンジニアへ転職後、受託開発でのさまざまな案件やベンチャー企業での新規自社サービス開発を経験し、現在はLINEヤフー株式会社で、社内におけるオープンソースの利用管理やオープンソースエコシステムへの貢献を推進するOSPO（Open Source Program Office）のメンバーとして、またLINEメッセージングアプリの開発に携わるiOSエンジニアとして働いている。
翻訳書: 『Good Code, Bad Code ～持続可能な開発のためのソフトウェアエンジニア的思考』、『Looks Good To Me』 他
石川 宗寿 / (@mntsh）/ LINEヤフー
新卒面接や新卒社員向けの教育改善、「LINE」の Android クライアントの開発に従事。「コード品質向上のテクニック」 というブログ連載を書いていた。
著書: 『読みやすいコードのガイドライン ―持続可能なソフトウェア開発のために』、『エンジニアチームの生産性の高め方 〜開発効率を向上させて、人を育てる仕組みを作る』
コメントを書くとき書かないとき
秋:
コードの保守性や可読性を語るとき、コメントは欠かせないテーマです。皆さんはどんな場面でコメントを残していますか？
森:
コメントについては『良いコードの道しるべ』『Good Code, Bad Code』『読みやすいコードのガイドライン』3冊全てで取り上げられています。
大切なポイントとして、コメントを追加して情報が増えるかどうかがあります。例えば関数名を文章化、もしくは和訳しただけのようなコメントは、メリットが薄く、むしろメンテナンスコストが増加するだけなので避けたほうが良いでしょう。反対に、情報量が増えるのであれば、積極的に追加するようにしています。
また、コメントを書くべきタイミングはある程度パターン化できると考えています。例えば、操作を主目的とし、結果をBool値などで返す関数です。このような関数名は、その操作に着目して名前をつけるため返り値の意味をメソッド名に含めるのは困難です。そのため、コメントで返り値の意味を補足することが重要になってきます。このように、パターンを覚えていくことがコメントを書く際に助けになると考えています。
高田:
私はコメントには「なぜ」を書くよう心がけています。例えば、メソッドが何をしているか、はコードを読むことでだいたいわかりますが、なぜそうする必要があるのか？というのは読み取りにくい場合があります。特に特殊なことをしている場合、なぜそういったコードになったのか、という背景をコメントに含めています。
秋:
私も、例えばログ出力しているコードに「ログ出力」といった、書き起こしただけのコメントは避けるようにしており、複雑になっているところにその背景をコメントに残しています。その上で、コメントなしでも意図が伝わるようなコードを心がけることが重要だと考えています。
石川:
補足として、ドキュメンテーションコメントとインラインコメントは分けて考えたほうが良いということを主張したいです。
ドキュメンテーションコメントは、クラスや関数といった要素に追加する形式的なコメントで、そのクラスや関数が何であるか、何をするかを説明するコメントです。コードを読まなくても理解ができるようにするという役割を持ちます。一方でインラインコメントはコードを読むときの補助をするためのコメントです。これらは大きく役割が異なるもので、ドキュメンテーションコメントはコードの中身が十分読みやすかったとしても、そのコードを読まずに理解ができるようにするために書く価値があります。
高田:
皆さんに質問したいんですが、ドキュメンテーションコメントを必須化すべきかってどう思いますか？
森:
LINEのAndroidアプリではクラスのドキュメンテーションコメントは必須で、他は任意になっています。個人的にはこのバランス感は良いと思っていて、すべての関数にドキュメンテーションコメントを追加しようとすると、冗長で無駄なコメントが発生しやすくなります。一方で、クラスは何かを抽象化するために作成されるので、その意図を説明することは有益なケースが多いと感じています。
もっとも、最適解はプロジェクトの規模やフェーズによって変わります。これはコードを読む人がかなり多いプロジェクトだからこそ合っている方針だと思うので、プロジェクトの規模やフェーズによって、採用すべき方針は異なるはずです。
石川:
私の個人的な意見としては、ドキュメンテーションコメントは積極的に書いてほしいなと思っています。例えば、データモデルといった単純なクラスであっても、そこに隠れたコンテキストが存在することは少なくありません。例えば値が取りうる範囲であったり、値の単位といった情報ですね。コードから読み取れない、書いた 人だけが知っている情報がないかを判断できるようになるには訓練が必要で、ドキュメンテーションコメントを書くことはそのよい訓練になると思っています。結果的にそのコメントがいらないなと思ったら、そのときに消せばよいので。
YAGNIと無計画 どう違う？
秋:
次のテーマは「YAGNIと無計画 どう違う？」というものですが、そもそもYAGNIって何の略か知っていますか？
石川:
「You Aren't Gonna Need It」あるいは「You Ain't Gonna Need It」の略です。
秋:
そうですね、YAGNIは「本当に必要になるまで実装しない」という原則です。一見すると「無計画」のように見えるかもしれませんが、YAGNIと無計画にはどんな違いがあるのでしょうか。
高田:
状況によってバランス感が多少異なると思います。ガチガチに計画を固めると、それに縛られてしまうし、全く無計画だと、その先の変更に対応できなくなります。ストリートコーダーという本にも、「何も考えないでコードを書く人は自分の時間を大切にしていない」というメッセージがあります。ある程度予測を立てて、柔軟に対応できる状態が望ましいと私は考えています。
秋:
例えば段階的に開発していく場合など、必要になるものが確定的にわかっている場合は、考慮しておくのが良いですね。また一度開発が終わった後も、必要に応じて機能を追加したり、逆に削ったり、軌道調整していくのもYAGNIの一環として捉えています。
石川:
ちょっと完璧な答えを言って良いですか（笑）。YAGNIは「今、必要でない機能は実装しない」ということを意味していて、そもそも機能の実装が必要かどうかの議論や設計をサボって良いということは意味していません。なので、YAGNIと無計画は完全に別の概念です。
森:
このお題、僕が考えたものなんですけど、実際にはYAGNIと計画性は反対に位置するとは思っていません。しっかりと未来を想像した上で、今やること、やらないことを決めるべきだと考えています。
一方で、未来の想像に時間をかけすぎてしまって、一向に前に進まないというのも陥りやすいパターンの一つです。ある程度考えたら、最後「えいや」で決めてしまうことも重要だと考えています。その際、必要最小限の機能を保守性が高い状態で実装できていれば、後からの変更も容易なはずです。
生成AIによってソフトウェアの保守性はどう変わる？
秋:
皆さんもコードを書く際に生成AIを活用されているかと思います。こういったツールによってソフトウェアの保守性はどのように変わっていくのでしょうか？1人ずつコメントを聞きたいと思います。
高田:
先に結論を述べると、特には変わらないと思っています。
生成AIを使うことで、人がコードを書く量は少なくなるかもしれません。ただ、AIが書いたコードを採用するかどうかなど、最終的には人が判断する必要があります。人が時間をかけてコードの良し悪しを判断する必要があるという面から、保守のコストは変わらないと考えています。
（補足：後々考えてみると、AIを使ってテストは書きやすくなるので 、テストが増えれば保守のコストを下げられそうです。とはいえ、人による保守は引き続き必要だと考えています。）
石川:
私も、ソフトウェアの保守性の重要さと、その性質はまだしばらくは大きく変わらないだろうと思っていて、それには大きく3つの理由があります。まず、生成AIのソースコードも元を辿れば、人間が書いたコードで学習し、「コードとしてのもっともらしさ」をベースに生成している、保守性が高さの概念について共通する点があるだろうという点。次に、現在の倫理観においては、人間が最終的に責任を持たなくてはならないため、人にとっての理解しやすさや改変しやすさが必要になる点。そして最後は、私が生成AIを実際使って感じていることなのですが、現在の生成AIは「知識が豊富だが経験は少ないジュニア」のような振る舞いをしているという点です。リファクタリングさせたり、既存のコードに機能追加させようとしたりすると顕著で、フラグを追加してその場しのぎの改変で済ませようとしたりするのですよね。
一方で、今後変わるかもしれないと思っている点もあって、それは人が見る保守性が一段高い概念になるかもしれないというものです。ソフトウェアの複雑性の限界は、人間の認知能力に依存している部分が大きいと考えています。今まで、高級言語、構造化プログラミング、フレームワークなどの登場で徐々にソフトウェアが複雑化していったのと同様に、生成AIが人間の認知能力の一部を担保するような状況になれば、今後、より複雑なソフトウェアが作られる可能性もあります。そのときは、一つメタな保守性の概念が必要になるか もしれません。
森:
この話題は非常に答えるのが難しいなと思っていて、来月何が出てくるかもわからない、将来が予測しにくい状況だなと感じています。すべてのコードをAIが書くようになって、人間はコードを見なくても良い、という未来になると、人がコードの保守性を気にする必要はなくなるでしょう。しかし、個人的には、そのような状況にすぐにはならないのではないか、今やっているようにAIにコードを書いてもらってレビューするというフローがしばらく続くのではないかと考えています。
そう考えたときに、ソフトウェアの保守性に対する知識はむしろ重要になると考えています。一つは、単にコードを書くだけでなく、全体像を見て判断ができるレビューできる人材がより必要になるということ。もう一つは、簡単なソフトウェアはAIが簡単に作れるようになることで、ソフトウェアがもっと複雑化することが想像できます。
そのため、このタイミングで保守性に関する勉強をすることは、むしろプラスになると考えています。何が言いたいかというと、『良いコードの道しるべ』や『Good Code, Bad Code』『読みやすいコードのガイドライン』をぜひ読んでくださいということになります（笑）
いかに保守性に対する意識をチームに浸透させるか
秋:
ここからは参加者から頂いた質問に回答していきたいと思います。1つ目の質問は「保守性に関する意識をチームに浸透させるかが肝な気もするのですが、そこらへんはどうしたらいいとかありますか？」という質問です。こちら石川さ んどうですか？
石川:
私がCode Readabilityのプレゼンテーションを作ったのは、まさにチームに意識を浸透させたいという目的でした。もともとは、コードレビューで何度も同じ指摘をするのが辛いという理由で、よくある指摘事項をまとめていき、それをプレゼンという形で共有しました。そして、チームに浸透させるには、一旦外部に公開して、外からの情報として共有するのも有効で、そのためにもプレゼンを一般公開したり、書籍化したりということを実施してきました。
森:
僕も前職で新卒研修でコードの保守性に関するプレゼンテーションを行ったことがあります。
組織全体に対して発信していくことも重要ですが、チームの内側から文化を変えていくことも可能だと考えています。具体的には、チーム内で気軽に雑談していくことはとても有効だと考えていて、「このコード、動くけれどもっと良い書き方があるかも」みたいな話が気軽にできるようになると、チームの意識も変わってくるように思います。
生成AIにレビューさせることに関してどう思われますか？
秋:
次の質問は「生成AIにレビューさせることに関してどう思われますか？たとえば同じチェックリストを持って学習させれば効率が上がるなど」というものです。こちらは先日レビューに関する本を翻訳された高田さんに聞いてみようと思います。
高田:
Looks Good To Meという本の第13章に、生成AIを使ったレビューについて書かれています。
まず、チェックリストを使うのはすご く良いと思います。あとは初回レビューにAIを使うことをおすすめします。メリットとして、生成AIはすぐにフィードバックをくれるため、レビュワーの反応を待たなくて良いという点が挙げられます。また、AIがつまらない初歩的なミスを指摘してくれるので、人間のレビュワーが本題に集中できる点も大きなメリットです。
注意点としては、使い始めはAIがプロジェクトの文脈やルールを理解していないため、求めているフィードバックが得られない可能性があります。そのため、時間をかけてAIに情報を蓄積しつつ、現在の信頼度を見極めることが重要になってきます。本の中ではレビューAIの精度を低、中、高という3つのレベルを使ってラベリングすることが提案されています。信頼度によってAIの結果をどう使うか、例えば無視できないエラーのように扱うのか、警告のように開発者が無視できるようにするのか、見定める必要があります。
もう一個の注意点として、AIの結果だけに頼るのはやめたほうが良いです。現状AIの返答は100%信頼できるとは言いづらく、人が最終的な判断をしたほうが良いでしょう。また、AIを過信することで自分のレビューする能力が落ちていってしまう危険性があります。
プログラミングの初心者が学ぶとき、最初から「良いコード」について学ぶのがよいか、最初は動くコードを書くことから学ぶのがよいか
秋:
最後に取り上げるのは、「プログラミングの初心者が学ぶとき、最初から「良いコー ド」について学ぶのがよいか、最初は動くコードを書くことから学ぶのがよいか、どう思いますか？」という質問です。こちら森さん回答お願いします。
森:
『良いコードの道しるべ』のまえがきにも書いているのですが、プログラミングの学び始めでコードを書くのが楽しくて仕方がないタイミングでは、目の前の作業に集中して良いと考えています。もしうまくいかないようなケースが増えたら、例えばバグが頻繁に発生するようであれば、保守性の原則を学ぶ最適なタイミングです。自分の経験に合わせて知識をつけていくことで、身についたスキルになると考えています。反対に、先に知識ばかりを手に入れてしまうと、不要に複雑な設計に走ったり、問題を抱えやすくなります。自分の成長段階に合わせて幅広く学んでいくことが重要だと考えています。
まとめ
急速な生成AIの進化で開発プロセスは変わりつつありますが、ソフトウェアを安定して開発し続けるという重要性変わらないと改めて感じました。また、今回のディスカッションを通じて、どのように保守性を上げることができるのか、より深く考えることができました。皆さんの開発現場でも、ぜひ似たようなテーマで議論を行ってもらえると、開発文化の醸成や品質向上に繋がるはずです。本記事がそのきっかけとなり、現場での新たな気づきや対話を生むことを願っています。
余談：イベントでは『良いコー ドの道しるべ』イラストを担当された久野さんとともにサイン会も実施しました。
書籍紹介
良いコードの道しるべ 変化に強いソフトウェアを作る原則と実践
森 篤史 著
動くコードを書くことは実はさほど難しくありません。 大事なのは書いたコードを他の人や将来の自分が読んで正しく理解できることです。 それが、継続的な開発をスムーズに進める鍵となります。 本書では、簡単に変更できる保守性が高いコードを「良いコード」と定義し、そのようなコードを書くための原則や手法を解説します。
https://book.mynavi.jp/ec/products/detail/id=147381
Good Code, Bad Code ～持続可能な開発のためのソフトウェアエンジニア的思考
Tom Long 著, 秋 勇紀 訳, 高田 新山 訳, 山本 大祐 監訳
本書では、GoogleのテックリードであるTom Long氏が、その知識と経験に基づいて「よいコード」と「悪いコード」を見極めるための概念やテクニックを紹介します。そのための「4つのゴール」「6つのコード品質の柱」を示し、具体的な事例を使って、なぜ「このコードはよい／悪いのか」を解説します。また、それを確認するためのユニットテストについても紹介します。プロのソフトウェアエンジニアとして必携の一冊です。
https://www.shuwasystem.co.jp/book/b620733.html
読みやすいコードのガイドライン -持続可能なソフトウェア開発のために
石川 宗寿 著
開発が大規模化・長期化するほど、コードを「読む」コストは増大していきます。そのため「読みやすさ」の向上は、生産性を改善し、プロダクトの成長限界を引き上げる重要な手段と言えるでしょう。 本書は、読みやすさの本質を学び、実践するための考え方をマスターできる一冊です。体系的な理解を実現するため、あらゆる角度から、豊富な例を交えて解説しています。表面的なテクニックではなく、いま目の前にあるコードに最適な改良方法を選び取る力が身に付きます。
https://gihyo.jp/book/2022/978-4-297-13036-7
Looks Good To Me ～みんなのコードレビュー
Adrienne Braganza 著, 高田新山 訳, 増井敏克 監訳
本書は、これまであまりなかったコードレビューの包括的ガイドです。 コードレビューに関わる人やグループの役割と責務、チームのレビュープロセス構築法、3Rパターンなど伝わるコードレビューコメントの書き方とメソッド、AIとコードレビューのこれから、などコードレビューの原理から実践テクニックまでを網羅した「コードレビューの最高の教科書」です。