shimopino / praha-challenges

exercises of PrAha Challenge
0 stars 0 forks source link

課題53「チーム開発を円滑にするコツを覚えよう」 #138

Open shimopino opened 3 years ago

shimopino commented 3 years ago

:question: 課題

What question? (課題の内容)

shimopino commented 2 years ago

Googleのプラクティスをまとめる

shimopino commented 2 years ago

CLでは何を伝えるべきか

CL: change list、コミットやプルリクなどいろいろあり

必ず伝えないといけないことは以下の2点

1行目に記載する内容は、他の開発者が検索する場合や、タイトルのみが表示される場合でも理解しやすい様に、具体的に何を変更したのかを簡潔に説明する必要がある。

それ以降は、変更に関する詳細な説明を追記する必要がある。欠陥があれば言及し、バグ番号や性能測定の結果、ドキュメントへのリンクなども含める可能性もある。

shimopino commented 2 years ago

具体例

shimopino commented 2 years ago

小さなCL

プルリクなどの変更を小さくしておくことには利点がある。

shimopino commented 2 years ago

小さなCLの具体的なサイズには特にルールはない。

小さなCLを作成するにあたっては、単純に差分の総量ではなく凝集度を考える必要がある。変更対象がただ1つの理由によるものに制限しておけば、自然と小さなCLを達成することができるはずである。

また、小さくするためにテストコードを分離することはしてはいけない。テストコードには対象物がどのように振る舞うべきか、その期待が入っているため、レビュワーが対象物を検証できるようにするにはCLと一緒にしておく必要がある。

https://twitter.com/t_wada/status/1281496033839550468?s=20

shimopino commented 2 years ago

小さなCLを実現するための1つのテクニックは、動作を変えないリファクタリングと、動作が変わる機能の変更を、異なるCLとして扱うことである。

shimopino commented 2 years ago

あるチームのコードレビューでは、レビュー時間と変更した行数との相関を計測しており、90%の確率で1時間以内にコードレビューを完了させたいのであれば、プルリクの上限をコード200行程度にするのがいいらしい。

https://smallbusinessprogramming.com/optimal-pull-request-size/

shimopino commented 2 years ago

コードレビューの基準

Googleでのコードレビュー中に期待する基準として以下を定めている。

一般に、ある CL が作業対象のシステムのコード全体の健全性を具体的に向上させる状態に一度でも達したならば、たとえその CL が完璧なものでなくても、レビュアは承認を賛成しなければならない。

これはレビュワーが求めているものが、完璧なコードではなく継続的な改善であるからである。

またコードレビューにはメンタリングの側面もある。レビュイーに対して、プログラミング言語やソフトウェア設計の一般原則に関して新しいことを教えるためにコメントを残すこともある。

ただし、上記の基準を満たすために必須ではない場合には、"Nit: "などのプレフィックスでその旨を表現しておく必要がある。

Nit: 細かい指摘 (nitpick)

shimopino commented 2 years ago

コードレビューの観点

shimopino commented 2 years ago

コードレビューのスピード

コードレビューは可能な限り迅速に行われるべきであり、返事をするまでにかかることが許される最大の時間として1営業日を推奨している。

よほどのことがない限り、1つのタスクに集中状態で取り掛かっている場合には、自身の作業を優先する。一休みできるタイミングでコードレビューを実施する。

shimopino commented 2 years ago

コードレビューにおいて重要なことの1つは、プロセス全体を高速に実施することよりも、1つ1つのレスポンスを高速にすることである。

忙しい場合であっても、いつレビューに取り掛かれるのかであったり、他のレビュワーを提案したり、最初は全般的なコメントのみを送ることだったりを迅速に実施すべきである。

shimopino commented 2 years ago

CLが大きすぎてレビューをする時間を確保できるのかわからない場合、開発者に大きなCLをお互いに構成された小さな複数のCLに分割することをお願いする必要がある。

shimopino commented 2 years ago

コードレビューでのコメント

通常、理解できないコードの説明を開発者にお願いした場合には、返事としてコードをより洗練されたものに書き換えることが期待される。

コードレビューツール上にしか書かれなかった説明は、将来のコードの読み手の助けにはならないこと理解しなければならない。

shimopino commented 2 years ago

Conventional Commits

明示的なコミット履歴を作成するための、軽量の規約を提供している。

<type>[optional scope]: <description>

[optional body]

[optional footer]

コミットの構造とセマンティックバージョニングとの対応は以下になる。

X. X. X
│  │  └ fix type: バグのパッチ
│  └─── feat type: 新しい機能の追加 
└────── BREAKING CHANGE type: APIの破壊的変更の導入

この規約に従うことで、自動化ツールの導入が可能となり、例えば以下のことが可能となる。

shimopino commented 2 years ago

Angular Commit Message Conventions

Conventional Commitsに従う形式で、Angularでは以下のようなコミットメッセージを記述している。

fix($compile): couple of unit tests for IE9

Older IEs serialize html uppercased, but IE9 does not...
Would be better to expect case insensitive, unfortunately jasmine does
not allow to user regexps for throw expectations.

Closes #392
Breaks foo.bar api, foo.baz should be used instead
shimopino commented 2 years ago

その他の参考記事

https://www.praha-inc.com/lab/posts/commit-message

shimopino commented 2 years ago

良さげなツール