「コードレビューに効く「読みやすさ」の処方箋」Findyでのオンライン講演 #コードレビュー_findy

Transcript

1. 森崎 修司 名古屋大学 大学院情報学研究科 コードレビューに効く「読みやすさ」の処方箋
2. 森崎 修司 - 自己紹介 • ソフトウェアエンジニアとして: ソフトウェア開発（2001～） – 通信事業者でオンラインストレージサービス開発 • 研究者として: 実証的ソフトウェア工学の研究（2005～） – ソフトウェア品質にかかわる研究に携わる。 – 文科省e-society基盤の総合開発、経産省 先進的ソフトウェア開発でソフトウェア工学の産学 連携の研究に従事 – 57社と機密保持契約ベースの共同研究 – 11人の社会人博士の学位審査と学位取得支援 – 独立行政法人情報処理推進機構(IPA) 「つながる世界の品質指針検討ワーキング・グルー プをはじめ3ワーキンググループの主査 2
3. アジェンダ • コードレビューで見つけるべき問題 • 読みやすさの分類 : Legibility, Readability, Understandability • 学術論文でのエビデンス • 読みにくくても誤読しにくいレビューアー(開発者)の特徴 • 生成AIにとっての読みやすさ 3
4. アジェンダ • コードレビューで見つけるべき問題 – コードレビューで見つけるべき問題 – オープンソースのコードレビュー（プルリクエスト）を調査した研究 – 人間にとっての読みやすさと生成AIにとっての読みやすさ • 読みやすさの分類 : Legibility, Readability, Understandability • 読みにくくても誤読しにくいレビューアー(開発者)の特徴 • 生成AIにとっての読みやすさ 4
5. コードレビューで見つけるべき問題 • 読みやすさ – 将来の拡張やバグ修正のときに開発者が理解しやすいか • バグや不備 – バグ（誤り、漏れ） – 不備（潜在的な拡張性の不備、非機能要求（性能、セキュリティ）の不充足 5
6. オープンソースのコードレビューでの読みやすさ改善の調査 • オープンソースのプルリクエストを調査した研究（文献[1]） – 対象 • ソースコード: GitHubのJavaソースコードの363のリポジトリのソースコード • プルリクエスト: アクセプトされコードの読みやすさ向上につながっているもの385件 – 調査 • プルリクエストがどのような読みにくいコード（コードスメル）を解消したか 6 文献[1] Oliveira, D., Santos, R., De Oliveira, B., Monperrus, M., Castor, F., & Madeiral, F. (2024). Understanding code understandability improvements in code reviews. IEEE Transactions on Software Engineering, 51(1), 14-37.
7. オープンソースのコードレビューでの読みやすさ改善の調査 • オープンソースのプルリクエストを調査した研究（文献[1]） – 対象 • ソースコード: GitHubのJavaソースコードの363のリポジトリのソースコード • プルリクエスト: アクセプトされコードの読みやすさ向上につながっているもの385件 – 調査 • プルリクエストがどのような読みにくいコード（コードスメル）を解消したか 7 出典: 文献[1] Oliveira, D., Santos, R., De Oliveira, B., Monperrus, M., Castor, F., & Madeiral, F. (2024). Understanding code understandability improvements in code reviews. IEEE Transactions on Software Engineering, 51(1), 14-37.
8. オープンソースでの読みやすさ改善の調査（結果） • コードスメルの分類（カッコ内は分類されたプルリクエストの割合と件数） – 不十分または不適切なコードの説明 (22.3%, 86件) – 不適切な識別子 (20.3%, 78件) – 複雑、冗長、または不適切なロジック (18.2%, 70件) – 不要なコード (13.2%, 51件) – 不一致または崩れたフォーマット (10.9%, 42件) – 誤り、漏れ、または不適切な文字列表現やリテラル (8.1%, 31件) – 不適切なロギングと監視 (4.7%, 18件) – 定数使用の漏れ (2.3%, 9件) • コードの読みやすさに関するプルリクエストの割合は42.2%であった。 • 既存Linterツールで検出できるコードスメルは30%未満であった。 8 出典: [1] Oliveira, D., Santos, R., De Oliveira, B., Monperrus, M., Castor, F., & Madeiral, F. (2024). Understanding code understandability improvements in code reviews. IEEE Transactions on Software Engineering, 51(1), 14-37.
9. 人間のコードの読みやすさと生成AIの読みやすさ • 人間と生成AIのコードの読みやすさは一致していなさそうだが、調査や研究はほ とんどない。 • 共通するものとそうでないものがある。 9 人間の読みやすさに影響を与えるもの 生成AIの読みやすさに影響を与えるもの
10. アジェンダ（再掲） • コードレビューで見つけるべき問題 • 読みやすさの分類 : Legibility, Readability, Understandability • 学術論文でのエビデンス • 読みにくくても誤読しにくいレビューアー(開発者)の特徴 • 生成AIにとっての読みやすさ 10
11. オープンソースでの読みやすさ改善の調査（結果） • コードスメルの分類（カッコ内は分類されたプルリクエストの割合と件数） – 不十分または不適切なコードの説明 (22.3%, 86件) – 不適切な識別子 (20.3%, 78件) – 複雑、冗長、または不適切なロジック (18.2%, 70件) – 不要なコード (13.2%, 51件) – 不一致または崩れたフォーマット (10.9%, 42件) – 誤り、漏れ、または不適切な文字列表現やリテラル (8.1%, 31件) – 不適切なロギングと監視 (4.7%, 18件) – 定数使用の漏れ (2.3%, 9件) 11 出典: [1] Oliveira, D., Santos, R., De Oliveira, B., Monperrus, M., Castor, F., & Madeiral, F. (2024). Understanding code understandability improvements in code reviews. IEEE Transactions on Software Engineering, 51(1), 14-37. コメント、ドキュメント 命名 構造、制御 デッドコード 判読性
12. アジェンダ（再掲） • コードレビューで見つけるべき問題 • 読みやすさの分類 : Legibility, Readability, Understandability • 学術論文でのエビデンス • 読みにくくても誤読しにくいレビューアー(開発者)の特徴 • 生成AIにとっての読みやすさ 12
13. 判読性（Legibility） • コードスメルの分類（カッコ内は分類されたプルリクエストの割合と件数） – 不十分または不適切なコードの説明 (22.3%, 86件) – 不適切な識別子 (20.3%, 78件) – 複雑、冗長、または不適切なロジック (18.2%, 70件) – 不要なコード (13.2%, 51件) – 不一致または崩れたフォーマット (10.9%, 42件) – 誤り、漏れ、または不適切な文字列表現やリテラル (8.1%, 31件) – 不適切なロギングと監視 (4.7%, 18件) – 定数使用の漏れ (2.3%, 9件) 13 出典: [1] Oliveira, D., Santos, R., De Oliveira, B., Monperrus, M., Castor, F., & Madeiral, F. (2024). Understanding code understandability improvements in code reviews. IEEE Transactions on Software Engineering, 51(1), 14-37. 判読性
14. 判読性（Legibility） • コードのレイアウトが読みやすさに与える影響を調査した論文をまとめたサーベイ 論文（文献[2]） – 空白(Spacing) – コードブロックの区切り(Block delimiters) – 長い/複雑なステートメント(Long or complex code line) – 単語の区切り(Word boundary styles) – 整形(Formatting style) 14 出典: 文献[2] Oliveira, Delano, et al. "A systematic literature review on the impact of formatting elements on program understandability." Available at SSRN 4182156 (2022)
15. 判読性 Legibility • 空白(Spacing) – インデントのスペースの数 – 複数の実験でインデントがないと統計的に有意に誤認、時間が増えることを報告 – 2, 4, 8といったスペースの数に関しては統計的に差があるとはいえないというものが 多い。 • コードブロックの区切り(Block delimiters) – {や}を独立した1行としたほうがよいか – 誤認識、時間に関して統計的に有意な差はない。 – 条件分岐等で紛らわしい場合には有意な差が報告されている。 15 出典: 文献[2] Oliveira, Delano, et al. "A systematic literature review on the impact of formatting elements on program understandability." Available at SSRN 4182156 (2022)
16. 判読性 Legibility • 長い/複雑なステートメント(Long or complex code line) – 1行あたり80文字以上の長いステートメント – 長すぎないほうがよいという意見が多いことが報告されている。 • 単語の区切り(Word boundary styles) – 複数の単語で構成される識別子の名称 例）minimum_valueとminimumValue – 識別子を探す実験において「_」でつないだほうが見落としが統計的に有意に少ないと いう報告がある。 • 整形(Formatting style) – Book format style, Pretty-printed style, Kerningham&Ritchie styleのように見た目を そろえるために空白行を入れる等の工夫 – 主観評価において、「好ましい」という回答が統計的に有意に多いという報告がある。 16 出典: 文献[2] Oliveira, Delano, et al. "A systematic literature review on the impact of formatting elements on program understandability." Available at SSRN 4182156 (2022)
17. オープンソースでの読みやすさ改善の調査（結果） • コードスメルの分類（カッコ内は分類されたプルリクエストの割合と件数） – 不十分または不適切なコードの説明 (22.3%, 86件) – 不適切な識別子 (20.3%, 78件) – 複雑、冗長、または不適切なロジック (18.2%, 70件) – 不要なコード (13.2%, 51件) – 不一致または崩れたフォーマット (10.9%, 42件) – 誤り、漏れ、または不適切な文字列表現やリテラル (8.1%, 31件) – 不適切なロギングと監視 (4.7%, 18件) – 定数使用の漏れ (2.3%, 9件) 17 出典: [1] Oliveira, D., Santos, R., De Oliveira, B., Monperrus, M., Castor, F., & Madeiral, F. (2024). Understanding code understandability improvements in code reviews. IEEE Transactions on Software Engineering, 51(1), 14-37. コメント、ドキュメント 命名
18. 命名やコメントとコードとの不整合に関する調査 • Linguistic Anti-patterns: 説明とコードの不整合 例） startという名称で終了している • オープンソースソフトウェアから名称、コメント、コードの不整合を取り出し、評価し た。（文献[3]） – ArgoUML, Cocoon, Eclipseから100個のファイルを無作為に選んで、「名前」「ドキュ メント」「コード」の間に不一致があるものを選んで、分類した。 → 6分類17種類 – 開発者に該当コードを読んでもらい「許容できる」「許容できない」を評価した。 → 70％近くのLinguistic Anti-patternsが「許容できない」と回答 ワースト3 • 「isValid」のような質問形式のメソッドで、論理値(Boolean)以外が返される。 • 属性（状態）の名称と型が反対の意味になっていて矛盾している。 • 属性（状態）の宣言部分で、反対の意味のコードコメントがある。 18 出典: 文献[3] Arnaoudova, V., Di Penta, M., & Antoniol, G. (2016). Linguistic antipatterns: What they are and how developers perceive them. Empirical Software Engineering, 21(1), 104-158.
19. Linguistic Anti-patterns （振る舞い） • A: 名前以上のことをする – 4種類 – 例） getメソッドが、値(属性)を返す以上の振る舞いをする。 • B: 実際の処理以上の名前がついている – 6種類 – 例） isOpened()のような質問形式なのに真理値（Boolean）型ではなく複雑な値を返 すメソッド • C: 名前と逆のことをする – 2種類 – 例） openという名称のメソッドが実際にはcloseに対応する動作をする。 19 出典: [3] Arnaoudova, V., Di Penta, M., & Antoniol, G. (2016). Linguistic antipatterns: What they are and how developers perceive them. Empirical Software Engineering, 21(1), 104-158. 和訳したものをブログエントリとして公開しています https://note.com/smorisaki/n/n2e6512920bb8
20. Linguistic Anti-patterns （属性（状態）） • D: 名前以上の属性（状態） – 2種類 – 例） 単数の名前（英語の単数形）なのに配列である。 • E: 属性（状態）以上の名前がついている – 1種類 – 例） 複数の名前（英語の複数形）なのに、単一の属性（状態）しかない。 • F: 名前と逆の属性（状態） – 2種類 – 例） startという名前がついている属性（状態）なのに、終了を表す属性として使われ ている。 20 出典: [3] Arnaoudova, V., Di Penta, M., & Antoniol, G. (2016). Linguistic antipatterns: What they are and how developers perceive them. Empirical Software Engineering, 21(1), 104-158. 和訳したものをブログエントリとして公開しています https://note.com/smorisaki/n/n2e6512920bb8
21. オープンソースでの読みやすさ改善の調査（結果） • コードスメルの分類（カッコ内は分類されたプルリクエストの割合と件数） – 不十分または不適切なコードの説明 (22.3%, 86件) – 不適切な識別子 (20.3%, 78件) – 複雑、冗長、または不適切なロジック (18.2%, 70件) – 不要なコード (13.2%, 51件) – 不一致または崩れたフォーマット (10.9%, 42件) – 誤り、漏れ、または不適切な文字列表現やリテラル (8.1%, 31件) – 不適切なロギングと監視 (4.7%, 18件) – 定数使用の漏れ (2.3%, 9件) 21 出典: [1] Oliveira, D., Santos, R., De Oliveira, B., Monperrus, M., Castor, F., & Madeiral, F. (2024). Understanding code understandability improvements in code reviews. IEEE Transactions on Software Engineering, 51(1), 14-37. 構造、制御
22. 誤読しやすい最小単位のコードを調査した研究 [4] • 国際Cソースコード難読化コンテストで上位であったもの(IOCCC: International Obfuscated C Code Contest) から15個の混乱コードの最小単位を抽出した。 – 4行程度で誤読させやすいコード片（Atoms of confusion）19種類を抽出 – 73名のプログラムにコードを読んでもらい、統計的に有意に誤読しやすいコード15種 類を選択 • オープンソースソフトウェアで該当するコードを抽出 – Linux, FreeBSD, Gecko, WebKit, GCC, Clang, MongoDB, MySQL, Emacs, Vim, Httpd, Nginx 22 出典: [4] Gopstein, D., Zhou, H. H., Frankl, P., & Cappos, J. (2018, May). Prevalence of confusing code in software projects: Atoms of confusion in the wild. In Proceedings of the 15th international conference on mining software repositories (pp. 281-291).
23. 誤読しやすい最小単位のコードを調査した研究 [4] 23 出典: [4] Gopstein, D., Zhou, H. H., Frankl, P., & Cappos, J. (2018, May). Prevalence of confusing code in software projects: Atoms of confusion in the wild. In Proceedings of the 15th international conference on mining software repositories (pp. 281-291).
24. 今回紹介できなかったもの • コードスメルの分類（カッコ内は分類されたプルリクエストの割合と件数） – 不十分または不適切なコードの説明 (22.3%, 86件) – 不適切な識別子 (20.3%, 78件) – 複雑、冗長、または不適切なロジック (18.2%, 70件) – 不要なコード (13.2%, 51件) – 不一致または崩れたフォーマット (10.9%, 42件) – 誤り、漏れ、または不適切な文字列表現やリテラル (8.1%, 31件) – 不適切なロギングと監視 (4.7%, 18件) – 定数使用の漏れ (2.3%, 9件) • 我々の研究グループで調査した命名と構造のどちらが誤読しやすいかを報告し ています。https://www.publickey1.jp/blog/24/post_301.html 24 出典: [1] Oliveira, D., Santos, R., De Oliveira, B., Monperrus, M., Castor, F., & Madeiral, F. (2024). Understanding code understandability improvements in code reviews. IEEE Transactions on Software Engineering, 51(1), 14-37. 構造、制御 デッドコード
25. アジェンダ（再掲） • コードレビューで見つけるべき問題 • 読みやすさの分類 : Legibility, Readability, Understandability • 学術論文でのエビデンス • 読みにくくても誤読しにくいレビューアー(開発者)の特徴 • 生成AIにとっての読みやすさ 25
26. 私の研究グループでの調査 文献[5] • 仮説: 誤読しやすいコードを正しく読める人は、慎重な意思決定をするはず • 評価方法: 慎重な意思決定をするかどうかを表す個人の属性であるモデルベー ス意思決定の割合と誤読しやすいコードの誤読率の関係を確かめる。 • 対象コード 8種類: – Atoms of confusionに含まれる、かつ、 – 車載用C言語コーディング規約であるMISRA-Cでも非推奨 • モデルベース意思決定 – 心理学で研究されている – 対象をモデル化してから意思決定するか経験により意思決定するかの割合(0～1) 26 出典: [5] Sugiyama, Y., Morisaki, S., Toyama, A., & Katahira, K. (2025). Relationship between Model-based Decision-making and the Comprehension Performance of Source Code with Confusing Patterns. IEEE Transactions on Software Engineering. 参考 https://note.com/smorisaki/n/n2a3756d8f21b
27. 私の研究グループでの調査 文献[5] 27 出典: [5] Sugiyama, Y., Morisaki, S., Toyama, A., & Katahira, K. (2025). Relationship between Model-based Decision-making and the Comprehension Performance of Source Code with Confusing Patterns. IEEE Transactions on Software Engineering. 参考 https://note.com/smorisaki/n/n2a3756d8f21b
28. 私の研究グループでの調査結果 文献[5] • 結果: 誤読しやすいコードにおいてのみ、モデルベース意思決定のほうが正解率 と関連していた。(有意水準 5%で統計的に有意な差) 28 出典: [5] Sugiyama, Y., Morisaki, S., Toyama, A., & Katahira, K. (2025). Relationship between Model-based Decision-making and the Comprehension Performance of Source Code with Confusing Patterns. IEEE Transactions on Software Engineering. 参考 https://note.com/smorisaki/n/n2a3756d8f21b わかりやすく変換 誤読しやすい
29. アジェンダ（再掲） • コードレビューで見つけるべき問題 • 読みやすさの分類 : Legibility, Readability, Understandability • 学術論文でのエビデンス • 読みにくくても誤読しにくいレビューアー(開発者)の特徴 • 生成AIにとっての読みやすさ 29
30. 生成AIにとっての可読性 • 人間と同様のものとそうでないものの両方があり、まだ十分には調査できていない。 • 人間とは異なる点を報告しているもの（文献[6] 2022年出版なのでモデルが古い） – 方法 • 120件のコードを生成する課題とコードの説明の課題を生成AIに出力させる。 • 生成AIの出力を4人の研究者が評価 – 妥当な内容か – ネットに公開されている情報でないか – 修正の必要があるか？ • 結果 – 大きなコードであっても、抽象的な説明はできず、特定箇所のみを説明してしまう – (x > 100)を「xが100より小さい」と説明してしまう等 30 出典: [6] Sarsa, S., Denny, P., Hellas, A., & Leinonen, J. (2022, August). Automatic generation of programming exercises and code explanations using large language models. In Proceedings of the 2022 ACM Conference on International Computing Education Research-Volume 1 (pp. 27-43).
31. 当日いただいた質問への回答 • 質問「生成AIへの指示が日本語、英語で結果は変わるのでしょうか？」 – 英語のほうが学習データが多いので、適切な表現ができればよりよい出力となるか もしれません。ただ、1, 2年前のようなプロンプトエンジニアリングによる効果は当時と 比べると小さくなっていると思います。 • 質問「資料8ページのコードスメルの分類での割合の母数は何ですか？」 – コードスメルとして分類したすべてのプルリクエストを100%としています。 31
32. 当日いただいた質問への回答 • 質問「よいコメントに関する研究はありますか？」 – 以下のサーベイ論文があります。 A decade of code comment quality assessment: A systematic literature review https://www.sciencedirect.com/science/article/pii/S0164121222001911 （サーベイ論文の読み方は以下のブログが参考になるかもしれません。 https://note.com/smorisaki/n/nda0ab8281ea7） • 質問「AIが生成したコードに含まれるコメントは多いように思うが少なくするよう指 示しておくべきでしょうか？」 – はい。「コードに書いてあることは含めないで決定理由等の背景をコメントとして書い てください」といった指示を出すことはできると思います。背景が学習データに存在す るような場合には効果が特に出そうです。 32
33. 当日いただいた質問への回答 • 質問「誤読しやすいコードでも正しく読めるように訓練する方法はありますか？」 – 慣れは一つ方法になると思います。26ページで紹介した研究の結果では、プログラ ミング経験年数が長い人は誤読しやすいコードを時間をかけて読んでいました。心 理学の研究でモデルベース意思決定の割合が大きい方でもストレスがかかっている とモデルベース意思決定の割合が減るという結果が報告されます。 • 質問「プルリクエストのサイズが読みやすさに影響する割合も大きいと思いますが 、コードスメルとは別の指標でしょうか？」 – はい。サイズが大きくなるとチェックがたいへんになる傾向にあるので、少なくとも2つ の指標は別々の影響と捉えることができると思います。プルリクエストのサイズとマー ジ（アクセプト）された割合の関係を調べた研究もあると思います。 33
34. 当日いただいた質問への回答 • 質問「読みやすさは定量的に測定できますか？」 – 一部できるものがありますができないことが多いです。コードの字句解析で求められ るものはできます。一般にネストが深いと読みにくいと指摘されていますが、これは字 句解析で数えられます。それ以外は今回のatoms of confusionの数を数えるといっ たことになると思います。 • 質問「コードの読みにくさをLegibility, readability, understandabilityに分類できた として、どれに注力すべきでしょうか？」 – バグが増えると困るようなソースコード(たとえば、共通ライブラリのような波及範囲の 大きいもの、変更頻度が大きいもの、バグのリスクが大きいもの)、開発メンバーや関 係者がストレスを強く感じるものから減らしていくのが得策だと思います。それがわか らなかったりてっとり早く知りたかったりということであれば、資料23ページのEffect size(効果量)の大きいものから順にというのが一つの方法になると思います。 34
35. 当日いただいた質問への回答 • 質問「読みやすさに関して認知心理学的な指標はありますか？人の能力を測る 仕様、慣れを合わせたものになりますか？」 – 一度に覚えておけるメソッドや変数の数のような認知負荷にもとづいてコードを評価 するCognitive complexity, Halstead complexity metricsがあります。 • 質問「不適切なロジックはバグとは違いますか？」 – 期待通りの動作はするけど「そんなふうに書かなくてもいいのに」というものが不適切 なロジックに該当すると思います。当然バグりやすそうですが、バグにはなっていない というものを指していると思います。 35