𝗢𝗽𝗲𝗻 𝘁𝗵𝗲 𝗣𝗥 𝘆𝗼𝘂𝗿 𝗿𝗲𝘃𝗶𝗲𝘄𝗲𝗿 𝗵𝗮𝘀 𝗻𝗼𝘁 𝗺𝗲𝘁 𝘆𝗲𝘁
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.
Sumber: https://dev.to/jeelvankhede/open-the-pr-your-reviewer-has-not-met-yet-4gfe
Komuniti pembelajaran pilihan: https://t.me/GyaanSetuAi