Upgrade to Pro — share decks privately, control downloads, hide ads and more …

CyberAgent AI Lab研修 / Code Review in a Team

chck
March 14, 2025

CyberAgent AI Lab研修 / Code Review in a Team

企業研究所AI Labの研修コンテンツ、「チーム開発から学ぶコードレビューのお作法」の資料です

chck

March 14, 2025
Tweet

More Decks by chck

Other Decks in Technology

Transcript

  1. 1 Code Review in a Team Yuki Iwazaki@chck | AI

    Lab Press Space for next page AI Lab Skill Up Onboarding 2024
  2. 1 Prerequisites x git command が使える ( git -v )

    x CyberAgentAILab/skillup2024-code-review にアクセスできる x CyberAgentAILab/skillup2024-code-review/projects で team-* Projects が見える 準備ができていない方も発表を聞いていれば一通り理解できるように作ってあります
  3. 1 Yuki Iwazaki @ chck 2014 … Backend Engineer in

    DSP 2017 … ML / DS in Ad Platform 2018 … Research Engineer in AI Lab github.com/chck Research Engineer | Applied ML
  4. 1 コードレビューとは A code review is a peer review of

    code that helps developers ensure or improve the code quality before they merge and ship it. 👍: 知識の共有 コードレビューに関わるメンバーの技術力を高めることができる。 👍: バグの早期発見 リリース後にリスクになるようなバグを未然に防げる。 👍: コンプライアンスの維持 コーディング規約への準拠を確認することで、複数人での開発に堅牢な実装を維持できる。 👍: セキュリティの強化 リリース後にリスクになるようなセキュリティ上の問題を防げる。 👍: コラボレーションの強化 情報の縦割り化を防ぎ、チームでプロジェクトを進めるためのコミュニケーションになる。 👍: コード品質の向上 Reviewer の知見を反映することでReviewee が見逃してしまう技術的負債を防げる。 🙅: コード提供の遅延 レビュー対応のやりとりによってコードの提供が遅れる。 🙅: レビューに時間がかかる コードレビューを優先する間、自身のタスクが進まなくなる。特に大規模コードのレビューは時間がかかる。 [1]
  5. 1 役割を決めよう 席を近づけて n 人組を作ってください 各グループ内でReviewee とReviewer に分かれよう Screen を見て一番左の方がReviewee

    それ以外は全員Reviewer Reviewee 人数 < Reviewer 人数になるように 作れたらReviewee 担当だけ挙手 🙌
  6. 1 研究計画を立てよう 締切までにやらなければいけないことを書き出す サーベイ データセット整備 手法の実装 実験結果のまとめ 執筆 今回は計画は既に立ててあることとします 2025-02-02

    2025-02-09 2025-02-16 2025-02-23 2025-03-02 2025-03-09 2025-03-16 2025-03-23 サーベイ データセット整備 手法の実装 実験計画決め Section Another 研究計画2025
  7. 1 Kanban を作ろう CyberAgentAILab/skillup2024-code-review にアクセス、Projects をクリック Projects -> New project

    -> Featured: Kanban -> Project name: "$ チーム名" -> Create project これも作ってあることとします GitHub のProject 機能
  8. 1 チケットを切ろう チケットは3 つの状態 (Draft, Issue, Pull Request) から選べる Issue

    は「既存研究のサーベイ」など、必ずしも実装と紐づけなくてOK 🙌 Hands-on: 今回は以下3 つのチケットをDraft で切ります 既存研究のサーベイ データセットの準備 提案手法の実装 Kanban board によるTodo のチケット化 各用語の関係性 Kanban board └── Ticket (Item) ├── Draft ├── Issue └── Pull Request
  9. 1 Branch を切ろう チーム開発や個人でも誰かへ共有予定のあるコードはレビューなくmain branch にpush してはいけない とにかくコードを変更したくなったらfeature branch を切ってそこで作業する

    main feature/issue-1 0-5478550 1-93316c9 2-06ccbf0 4-be68977 著名なBranch 戦略であるgit-flow をベースに、研究機関としてシンプルにしたもの main : 開発時のバグや実行時エラーが解消されている安定的なBranch feature/* : 新機能の追加や既存機能の変更を行うBranch
  10. 1 Hands-on: Branch を切ろう リポジトリをClone ※ $team にはチーム名を入れる 例えばteam blue

    の場合は git clone https://github.com/CyberAgentAILab/skillup2024-code-review.git cd skillup2024-code-review git checkout -b feature/issue-$team git checkout -b feature/issue-blue
  11. 1 Note: Product use develop や hotfix branch が増え、Production の事故を極力減らした構成に

    main develop feature/issue-1 hotfix/issue-2 0-534544e 1-2f01b85 2-7b282a6 3-345b864 6-fac3783 7-fdfbfa5 develop : main にマージするまで開発の中心となるBranch hotfix/* : main に対して緊急の修正を行うBranch 1. https://future-architect.github.io/coding-standards/documents/forGitBranch/git_branch_standards.html ↩︎ [1]
  12. 1 実装しよう 何よりも再現性と構造化 ラスタ画像、UI ポチポチなど非可逆的なフォーマットを極力減らし、差分を確認しやすい状態を作る Markdown, Mermaid, Terraform 手順の多いコマンド処理は自動化する Shell

    Script, Makefile, Makefile.toml, Taskfile.yml Project の構成を意識する ディレクトリ構造、モジュール分割、クラス設計 今回は既に実装済のコードが用意してあります Hands-on: 実装済のコードを引っ張ってくる Hands-on: 差分を確認する git pull --rebase origin feature/sample git diff main origin/feature/sample -- ':!docs'
  13. 1 Commit をしよう 今回は既にcommit 済のものを眺めてみる Hands-on: Commit 履歴を表示 Hands-on: Commit

    履歴を簡略化して表示 このようにオプションが複雑なものはgit alias を設定しておくと便利 git log git log --graph --pretty=oneline --decorate --date=short --abbrev-commit --branches
  14. 1 Tips: Commit message に迷ったら Semantic Commit Messages: Google/Angular の規約にアレンジを加えたもの。実装内容によって7

    types を使い分ける type description example chore 微修正 chore: fix typo docs ドキュメント関連の変更 docs: add readme how to run feat コードの本体機能に関する追加・変更 feat: modify dependencies for training fix バグ修正 fix: ensure loss function returns non-zero refactor パフォーマンス改善等のリファクタリング refactor: improve model loading style フォーマット等の見た目上の変更 style: apply ruff linting Commit Message の規約に従う feat: add hat wobble ^--^ ^------------^ | +-> Summary in present tense. +-------> Type: chore, docs, feat, fix, refactor, style, or test.
  15. 1 Pull Request (PR) を上げよう Pull Request: 実装内容をmain に取り込む (merge

    する) ためのリクエスト 作業途中でもいいのでDraft でPR を上げる こまめに進捗共有するのと同義 Draft もなくいきなり200 files のPR が来たらレビューコストも高い コミットを整理する PR の説明欄にはどんな変更をしたかを書く Issue とPR を紐付ける ( まとめられるならCommit でもOK) PR のテンプレートを活用する 見てほしい人をReviewer に指名する Reviewee 側のお作法
  16. 1 Hands-on: Pull Request (PR) を上げよう ※ $team にはチーム名を入れる 例えばteam

    blue の場合は CyberAgentAILab/skillup2024-code-review にアクセス、 main <- 該当Branch でCreate Pull request git push origin feature/issue-$team git push origin feature/issue-blue
  17. 1 Hands-on: Pull Request (PR) を上げよう 1. PR のDraft 化

    2. 実装 ( 今回はskip) 3. レビューができる状態になったらReady for review ボタンでDraft を解除しReviewer にリクエスト
  18. 1 レビューをしよう 設計: コードはうまく設計され、そのシステムにとって適切か? 機能性: コードは作成者の意図通りに動作するか?ユーザーにとってコードの挙動は適切か? 複雑さ: コードはもっとシンプルにできるか? コードを作成した開発者があとになってもう一度そのコードに触れたとき、理解しやすく使いやすいか? テスト:

    そのコードには、正確で、うまく設計され、自動化されたテストがあるか? 命名: 変数名、クラス名、メソッド名などに明解な名前を選んだか? コメント: コメントは明解で有益か? スタイル: コードはスタイルガイドに準拠しているか? ドキュメント: 関連するドキュメントも更新してあるか? 1. https://fujiharuka.github.io/google-eng-practices-ja/ja/review/ ↩︎ 具体的な8 種類のレビューポイント[1]
  19. 1 Tips: レビューコメントのラベル化 label description [must] 必須。明らかに実装が間違っているとき [imo] 私の意見では。直してほしいけど必須ではない [nits]

    細かい指摘。typo とか [fyi] 参考までに。関連記事のURL を貼ったり [ask] 質問。実装の意図を深堀って聞きたいとき 例 [must] この依存は使われていないので消したほうが良いかもです [ask] このA 関数はB 関数とどうやって使い分ける想定でしょうか 優先度のニュアンスを伝える
  20. 1 Hands-on: レビューをしよう レビュー依頼が来たら自分のタスクに割り込んででも早く対応する 最長でも1 日以内、ボールを止めている意識を持つ 特に大きなプロジェクトの場合main branch がどんどん進んでしまいMerge が困難に

    Hands-on: PR 画面 -> Files changed -> Start a review -> Comment -> Submit review ファイル単位でレビュー済かどうかをチェックする機能 行を指定してコメントを残す機能 直接コードに修正案も書ける 1. https://fujiharuka.github.io/google-eng-practices-ja/ja/review/reviewer/speed.html ↩︎ [1]
  21. 1 PR をマージしよう 基本的には PR ページ下の Merge pull request ボタンを押すだけ

    (コンフリクトが予想されるためこのハンズオンでは押さない) おつかれさまでした!
  22. 1 リリース(main merge )後の開発サイクルについて Document を書こう README.md やHelp Page の充実

    Issue に返信しよう ユーザーは最大のdebugger 依存パッケージを定期的にアップデートしよう 古いコードでも今の依存で動くようメンテされていれば長く使ってもらえる リリースノートを書こう 最近のアップデートでどんな変更を行ったのか
  23. 1 まとめ Kanban を使ってタスク管理からPull Request のマージまでを体験 研究コードは普段からGit 管理をしよう 開発力/ コードレビュー力を上げるためにできること

    チーム開発をしよう 共著なら実験途中からGitHub を使おう ペアプロ、モブプロをしよう 単著でもお互いのProject code を見せ合おう お手本から学ぶ コードスニペットを集めよう LLM に訊くのも良いが、GitHub 内検索も有効 Reading 9 : Writing 1 詳しい人に訊こう
  24. 1 Note: 良いコードとは 動くコード vs 綺麗なコード 該当する品質特性 解決したい問題 動くコード 機能性

    収益の向上 綺麗なコード 変更容易性 開発コストの低減 動くコード:綺麗なコードを書くのに時間を割いていられない 綺麗なコード:綺麗なコードを書かないと保守や変更が大変になる AI Lab のような研究機関における2 つの収益 a. 実験サイクルを高速化し、論文の締切に間に合わせ、トップカンファレンスに採択される b. 利用者に再現しやすいコードを公開し、研究成果をコミュニティに広める 1. https://developersblog.dmm.com/entry/2024/11/01/110000 ↩︎ [1]
  25. 1 Note: 幻のRefactor フェーズ 2024-10-20 2024-10-27 2024-11-032024-11-10 2024-11-17 2024-11-24 2024-12-012024-12-08

    2024-12-15 2024-12-22 2024-12-292025-01-05 2025-01-12 2025-01-19 2025-01-262025-02-02 2025-02-09 2025-02-16 動くコード( R&D フェーズ) そこそこ綺麗なコード( R&D フェーズ) Paper Deadline/Production Deploy 綺麗なコード( Refactor フェーズ) 綺麗なコード( Refactor フェーズ) パターン1 パターン2 締め切りを起点にした研究コードの品質 パターン1 :動くコードから綺麗なコードへのRefactor コストが高い パターン2 :普段からそこそこメンテできているコードはRefactor コストが低い 締め切りを起点にした研究コードの品質
  26. 1 CI を活用しよう Ruff + pre-commit でコミット時にコード品質を保ちたい GitHub Copilot コード

    レビューの使用 GitHub Actions でPython のLint とTest (テスト)をとりあえず実行 GitHub Actions で Python コードの自動フォーマットを実現しよう