English Vocabulary for Software Developers, Lesson 9: Constructive Code Reviews (PR Etiquette)
Lesson Goals
- Transition from rigid, overly blunt feedback habits to an empathetic and collaborative international code review style.
- Write clear, constructive Pull Request comments that focus on code quality rather than the developer’s identity.
- Master industry-standard acronyms, tags, and frameworks used during global peer reviews.
Target Vocabulary
- Pull Request (PR) / Merge Request (MR) / Пулл-реквест / Мерж-реквест
- Definition: A proposed set of code changes submitted by a developer for peer review and approval before being merged into the main codebase.
- LGTM (Looks Good To Me) / Выглядит отлично (сокращение при одобрении кода)
- Definition: A widely used professional acronym posted in PR comments to signal that the code has been reviewed, meets team standards, and is ready for merging.
- Nitpick (Nit) / Придирка / Мелкое замечание (нитпик)
- Definition: A minor, non-blocking feedback point or stylistic preference during a code review that does not affect functionality or safety.
- Technical Debt / Технический долг
- Definition: The implied cost of future additional rework caused by choosing an easy or messy software solution now instead of using a better, long-term approach.
- Refactoring / Рефакторинг (перепроектирование кода)
- Definition: The process of restructuring existing computer code without changing its external behavior, aimed at improving readability, complexity, or maintainability.
- Approvals / Одобрения (аппрувы)
- Definition: Formal digital sign-offs within repository platforms (like GitHub or GitLab) required from designated team members before code can be merged into production.
Reading Passage 1: Industry Overview
In many domestic engineering cultures across the post-Soviet region, code reviews can feel adversarial, direct, and hyper-focused on correcting mistakes. Comments like “This is wrong,”“Rewrite this,” or “Why did you use this pattern?” are common. While not intended as personal attacks, this rigid phrasing violates international PR etiquette. Global tech cultures heavily emphasize psychological safety and separate an engineer’s identity from the code they write. Reviewers are expected to frame feedback as collaborative suggestions rather than strict commands. If an issue is minor or purely stylistic, it is tagged as a nitpick, signaling to the author that it is non-blocking. When major restructuring is needed to avoid introducing technical debt, reviewers frame it as a shared goal for future refactoring. Developers must learn that giving and receiving feedback is a conversation, where securing final approvals and an LGTM relies heavily on mutual respect and objective communication.
Reading Passage 2: Dialogue: Polishing the Pull Request
Nikita (Backend Developer): Hey Jessica, I just looked over your review on my new database optimization Pull Request. Honestly, I feel a bit discouraged. You left twelve comments on my code, and back at my old company, that usually meant your code was terrible.
Jessica (Tech Lead): Oh, Nikita, please don’t take it that way at all! The code is actually very solid, and your logic is great. In global engineering teams, a lot of comments just mean we are actively collaborating to keep the codebase clean. It’s never a judgment of your capabilities.
Nikita: That’s a relief. I noticed you started three comments with the word “Nit.” What does that mean? Is it a critical bug?
Jessica: Not at all! A nitpick means it’s just a tiny, minor detail—like an extra empty line or a naming convention that fits our style guide slightly better. You don’t even have to change it if you don’t want to; it won’t block your final approvals.
Nikita: Ah, I see. But you also mentioned that my loop might increase our technical debt. How should I fix that?
Jessica: If we leave that nested loop as it is, it will be very hard for the next developer to scale it when our dataset grows. I suggested some refactoring to break that logic into a separate helper utility. It will make the system much easier to maintain long-term.
Nikita: That makes total sense. I’ll implement those architectural adjustments right now. Once I push the new commits, do I need to ping you again for an LGTM?
Jessica: Yes, just re-request a review on GitHub. Once I verify the refactored loop, I’ll gladly drop an LGTM and approve the code so you can merge it into production.
Grammar & Usage Section: Framing Constructive Feedback
To align with international code review standards, steer away from imperative verbs or phrases directed at the person (“You forgot…”, “Your code is slow”). Instead, use passive voice structures, inclusive pronouns (“we”, “our”), and soft inquisitive phrasing to focus entirely on the code.
- Instead of: “You need to fix this naming convention.”
- Use: “Nit: Let’s update this variable name to follow our camelCase styling conventions.”
- Instead of: “Why did you use a global state here? It’s bad.”
- Use: “Could you clarify the choice of a global state here? I’m wondering if a local state might help us avoid unexpected side effects.”
- Instead of: “Your function is creating technical debt. Rewrite it.”
- Use: “To prevent building up technical debt, it might be worth refactoring this logic into smaller, testable sub-functions.”
- Approving code with minor adjustments: “Everything looks great. LGTM once the test coverage is updated!”
Practice Exercises
Part 1: Fill in the Blanks
Complete the sentences using the target vocabulary from this lesson.
- I cannot merge my branch into the master environment because our repository configuration requires at least two independent peer ________.
- If we keep rushing features to production without writing automated tests, our team will accumulate massive ________.
- The Senior Architect left an ________ on my branch, writing that the layout was clean, optimal, and ready to ship.
- I spent my afternoon doing code ________, clean-coding three old legacy methods to make them more readable without changing their core behavior.
- ________: There is a small typo in the documentation block on line 45, but feel free to fix it in a future branch.
Part 2: PR Feedback Transformation Challenge
Rewrite these blunt, confrontational code review comments into polite, empathetic, and professional English phrases suitable for an international team.
- Blunt:This code is messy. Clean this up before merging.
- (Rewrite focusing on refactoring and readability using inclusive pronouns like “we”)
- Blunt:You forgot to handle the error case here. Fix it.
- (Rewrite as an inquisitive or soft suggestion focusing on the system behavior)
- Blunt:Bad performance. Don’t use this map loop.
- (Rewrite by pointing out the computational impact objectively and proposing an alternative)