𝗢𝗽𝗲𝗻 𝘁𝗵𝗲 𝗣𝗥 𝘆𝗼𝘂𝗿 𝗿𝗲𝘃𝗶𝗲𝘄𝗲𝗿 𝗵𝗮𝘀 𝗻𝗼𝘁 𝗺𝗲𝘁 𝘆𝗲𝘁
I reviewed a large pull request recently. It used AI to help write the code. It changed a module that three other features used. The description was only one sentence. It named the file but not the reason for the change.
I spent fifteen minutes mapping the changes before I could start. I had to find the intent. I had to find the risks. I had to separate the important files from the noise.
I realized I had done this to someone else before.
When you write code, you carry all the context. You know why you split a module. You know what you tried first. You know which parts you feel unsure about.
Most people write descriptions for themselves. They write "Refactored service layer" or "Fixed auth module." These are descriptions for people who already know the context.
A good description is for the person who knows nothing.
A description is not just a summary. It is a test. If you cannot explain your work, your work is not ready.
I now use a six-part structure for every non-trivial PR:
• Intent: Explain why this PR exists and the problem it solves. If you cannot write this, stop. The PR is not ready. • Major changes: List decisions that affect architecture or existing behavior. • Minor changes: List cleanups and renames. Keep them separate from structural changes. • Impact: List the systems this touches. Provide a map of the blast radius. • Evidence: List what you ran and what tests you passed. Show proof that you did the work. • Uncertainties: State what you are unsure about.
When you admit uncertainty, you help the reviewer. They know where to look closely. They do not waste time on parts that are working fine.
If you cannot name your uncertainties, you have not thought deeply enough about your code.
The description is the last step before you decide if a PR should even open.
A reviewer who understands your intent spends time on hard questions. A reviewer who must guess your intent spends time on easy questions. They ask what things are instead of asking if they are right.
Write for the reviewer who has not met your code yet. Write as if you will not be there to answer questions. Write as if you are reading it three days from now with no memory of the work.
If the description holds up, the PR is ready.
PRを出そう。レビュアーはまだあなたのコードに出会っていないのだから
私たちは皆、同じ経験をしたことがあります。数日間、ある機能の開発に取り組んできました。コードを磨き上げ、テストも済ませ、ようやく提出する準備が整いました。しかし、そこで躊躇してしまうのです。
「まだ完璧じゃないのではないか？」 「先にこの部分をリファクタリングすべきか？」 「もし根本的な欠陥が見つかったらどうしよう？」
私たちがよく陥る間違いは、PR（プルリクエスト）を開く前に、コードを「完璧」にしようと待ってしまうことです。これは罠です。
早期フィードバックの重要性
早い段階でPRを開くことで、早期にフィードバックを得ることができます。1,000行のコードを書いた後よりも、まだ100行しか書いていない時の方が、方向転換ははるかに簡単です。
もしあなたの設計思想に根本的な誤りがあった場合、最後まで待ってしまうと、膨大な量のコードを書き直すことになります。しかし、早い段階でPRを出していれば、最小限の修正で済むかもしれません。
PRは対話の手段である
PRは単にコードをマージするためのリクエストではありません。それは対話のきっかけです。「これが私の考えたアプローチです。どう思いますか？」と伝える手段なのです。
コードが完成していなくても、あなたの考えを共有することで、チームメイトから新しい視点や、より良い解決策を提案してもらえる可能性があります。
「完璧主義」という罠
完璧主義は、一見すると美徳のように思えますが、開発においてはしばしば進捗を妨げる要因となります。
「完璧なコード」というものは存在しません。コードは常に進化し、改善されるものです。重要なのは、コードを完成させることではなく、価値を提供し、チームと共に成長することです。
解決策：Draft PRを活用しよう
「まだ完成していないからPRを出せない」という不安があるなら、Draft PRを活用しましょう。
Draft PRは、「まだ作業中ですが、方向性が合っているか確認してほしい」という意思表示として最適です。これにより、以下のメリットが得られます。
- 早期のレビュー: 設計やアプローチに関するフィードバックを早い段階で得られる。
- 透明性の向上: あなたが今何に取り組んでいるのかをチームに知らせることができる。
- 心理的ハードルの低下: 「未完成であること」を公式に認めることで、レビューへの心理的な抵抗が減る。
まとめ
完璧を待たないでください。PRを出しましょう。
レビュアーはまだあなたのコードに出会っていません。彼らに、あなたのコードと対話する機会を与えてあげてください。
Optional learning community: https://t.me/GyaanSetuAi