How to Discuss Code Quality in English

Code reviews are one of the most common places where software developers need precise English. You need to describe problems clearly, suggest alternatives respectfully, and avoid sounding either vague or harsh. At the same time, you need to understand when a colleague is raising a legitimate quality concern versus a personal style preference. This post gives you the vocabulary and phrases to navigate code quality conversations with confidence.

Key Phrases

Describing complexity:

• “This increases the cyclomatic complexity of the function — it already has eight branches.”
• “The cognitive load here is high. I had to read this three times to understand what it does.”
• “I’d extract this into a separate function to make the intent clearer.”
• “This method is doing too much — it’s violating the single responsibility principle.”

Identifying design problems:

• “There’s a violation of the single responsibility principle here — this class handles both authentication and logging.”
• “This pattern is brittle because it relies on the internal state of another module.”
• “We have tight coupling between these two services — a change in one will likely break the other.”
• “The abstraction level is inconsistent — some methods are high-level while others are implementation details.”

Suggesting improvements:

• “I’d extract this into a separate module to improve testability.”
• “Let’s aim for higher cohesion within this class and lower coupling to its dependencies.”
• “Could we replace this switch statement with a strategy pattern?”
• “I’d consider using dependency injection here to make this easier to test in isolation.”

Framing feedback constructively:

• “This works, but I’m concerned about maintainability as the codebase grows.”
• “I see what you’re going for here — would it be worth considering an alternative where…”
• “Nit: this variable name could be more descriptive. Not a blocker, just a suggestion.”
• “This is a blocker for me — the lack of error handling could cause silent failures in production.”

How to Use This in Practice

In code reviews, the tone of your feedback matters as much as the content. English-speaking teams typically use a scale of severity:

• Blocker / Must fix — “This is a blocker — it will cause data loss in edge cases.”
• Should fix — “I’d really prefer if we addressed this before merging — the coupling here will make future changes painful.”
• Nit (nitpick) — “Nit: minor style issue, not a blocker.”
• Suggestion — “Optional: just something to consider for future refactoring.”

Prefix your feedback with “Nit:” or “Suggestion:” so the author knows what level of urgency you intend. This is standard in teams at Google, Meta, and many large tech companies.

When you say something “increases cyclomatic complexity,” you are saying it has too many independent code paths (branches, loops, conditions). You can make this concrete: “This function has a cyclomatic complexity of 14. Anything above 10 becomes difficult to test exhaustively.”

Cohesion refers to how closely related the responsibilities within a module are. High cohesion is good — everything in the module belongs together. Coupling refers to how much modules depend on each other. Low coupling is good — modules can change independently.

Example Conversation

Reviewer (Maksym): “I’ve left a few comments on the PR. The main one is a blocker — the authentication logic and the email notification are in the same function, which is a violation of the single responsibility principle. If we need to swap out the email provider, we’d have to touch authentication code.”

Author: “Good catch. Would it make sense to extract the notification into a separate service class?”

Maksym: “Exactly. That would give us lower coupling and make both parts independently testable. I also left a nit about variable naming in the loop — not a blocker, but the name i doesn’t convey much intent when iterating over userRecords.”

Author: “Agreed. I’ll rename it to userRecord and extract the notification logic before requesting re-review.”

Practice Tips

1. Review code on GitHub with vocabulary in mind: Next time you read a pull request discussion on a public repository (GitHub has millions of open PRs), highlight every phrase that describes a code quality concern. Notice how native speakers frame blockers versus suggestions.

2. Rewrite a vague comment into a precise one: Take a vague code comment like “this is messy” and rewrite it using the vocabulary from this post. For example: “This increases cyclomatic complexity and violates the single responsibility principle — I’d extract the validation logic into a separate class.”

3. Practise the cohesion/coupling distinction: Think of two examples from your own codebase — one where cohesion is high (a module that does one thing well) and one where coupling is high (two modules that are difficult to change independently). Describe each example in English using the terms from this post.