English Vocabulary for Code Architecture Discussions

Architecture discussions are among the most vocabulary-dense conversations in software engineering. If you’re not fluent in the terms your team uses, it’s easy to nod along without fully understanding — or worse, to propose solutions that miss the design intent. This post covers the core English vocabulary you need to participate confidently in architecture and design review conversations.

Key Vocabulary

Coupling and cohesion Two fundamental concepts always discussed together. Coupling describes how dependent two modules are on each other — high coupling is bad. Cohesion describes how focused a module is on a single purpose — high cohesion is good. The goal is “low coupling, high cohesion.” Example: “The problem here is high coupling between the order service and the inventory service. A change to one always breaks the other.”

Separation of concerns (SoC) The principle that different parts of a system should handle different responsibilities and not overlap. Often used to argue against mixing business logic with data access or UI code. Example: “We’re violating separation of concerns by putting database queries directly in the controller.”

Single responsibility principle (SRP) Each module, class, or function should have exactly one reason to change. Part of the SOLID principles, frequently cited in code reviews. Example: “This class is doing validation, persistence, and email notification — it has three responsibilities. We should split it.”

Dependency inversion High-level modules should not depend on low-level modules; both should depend on abstractions. Enables flexibility and testability by decoupling implementation details. Example: “Instead of depending directly on the MySQL client, we should depend on a repository interface — that’s dependency inversion.”

Bounded context A term from Domain-Driven Design (DDD). A boundary within which a particular model and terminology applies. Two bounded contexts can use the same word (like “customer”) to mean different things. Example: “In the billing bounded context, ‘customer’ means an account with payment history. In the CRM context, it means a contact record. We need to be explicit about which context we’re in.”

Anti-corruption layer (ACL) A translation layer that sits between two systems (or bounded contexts) to prevent one system’s model from leaking into another. Common when integrating with legacy systems. Example: “We built an anti-corruption layer between our new order service and the legacy ERP system so we don’t have to mirror its messy data model.”

Strangler fig pattern A migration strategy where new functionality is built around an existing system, gradually replacing it until the old system can be removed — like the strangler fig tree that grows around and eventually replaces its host. Example: “We’re using the strangler fig pattern to incrementally replace the monolith without a risky big-bang rewrite.”

Architecture fitness function An automated test or metric that checks whether the system still conforms to its architectural goals. Think of it as a unit test for architecture decisions. Example: “We have a fitness function that fails the build if any module in the domain layer imports from the infrastructure layer.”

Seam A place in the code where behavior can be altered without modifying existing code — typically an interface, an abstraction point, or a plugin boundary. Example: “We need to introduce a seam here so we can inject a test double without modifying the production code.”

Common Phrases and Collocations

“This violates [principle]” A standard code review phrase for flagging architectural problems. Example: “This violates the single responsibility principle — the service is handling both business logic and HTTP response formatting.”

“We should introduce an abstraction here” Suggests adding an interface or abstract layer to reduce coupling. Example: “We should introduce an abstraction here — that way we can swap the storage backend without changing the business logic.”

“What’s the blast radius if this changes?” Ask this to evaluate how widely a change will propagate through the system — a proxy for coupling. Example: “What’s the blast radius if we change the user schema? How many services will we need to update?”

“This leaks [detail] into [layer]” Used to flag cases where a concern from one layer is inappropriately visible in another. Example: “This leaks database column names into the API response — that’s a separation of concerns issue.”

“We’re crossing bounded context boundaries” A flag that two domains are being inappropriately coupled. Example: “If we call the billing service directly from the shipping service, we’re crossing bounded context boundaries. We should use an event instead.”

Practical Sentences to Practice

1. “The coupling between these two modules is too tight — a schema change in one service forces a deployment in three others.”
2. “We should define a bounded context for the notification domain and give it its own model rather than reusing the user entity from auth.”
3. “I’d suggest introducing an anti-corruption layer to translate the legacy API’s data model into our internal representation.”
4. “This fitness function will catch any future violations of the layered architecture automatically.”
5. “The strangler fig approach lets us migrate incrementally rather than committing to a full rewrite.”

Common Mistakes to Avoid

Confusing “coupling” and “dependency” All coupling involves dependencies, but not all dependencies are problematic coupling. The key is whether the dependency is on a stable abstraction (good) or a concrete implementation (risky). Instead of: “These classes are coupled because one imports the other.” Say: “These classes are tightly coupled because the caller depends on the internal implementation details of the callee.”

Using “separation of concerns” and “single responsibility” interchangeably They’re related but different. SoC is about separating different types of concerns (e.g., UI vs. business logic). SRP is about a module having only one reason to change. You can satisfy one without the other.

Saying “clean architecture” without specifying what’s wrong “Clean architecture” is a vague compliment or complaint. Be specific in reviews. Instead of: “This isn’t clean architecture.” Say: “The domain layer is importing from the infrastructure layer, which reverses the dependency direction we agreed on.”

Summary

Architecture vocabulary is the shared language that lets engineering teams make and communicate design decisions precisely. Whether you’re in a code review flagging a separation of concerns violation, or in a design session proposing a strangler fig migration, using the right terms signals that you understand the principles — not just the patterns. Study these terms in context, and practice using them in your next design discussion.

Navigating Nuance: Addressing Ambiguity & Seeking Clarification

One of the biggest hurdles for non-native English speakers in a technical environment is not just understanding individual words but grasping subtle nuances of meaning – particularly when it comes to expressing uncertainty or seeking clarification. It’s far more acceptable, and often preferred, than simply stating an opinion without backing it up with evidence or acknowledging potential alternative interpretations. Think about the difference between saying “This is wrong” versus “I’m seeing a potential issue here; could we explore [alternative]?” The latter invites discussion rather than shutting it down.

A common scenario arises during code reviews. Let’s say you spot a section of code that seems unnecessarily complex. Instead of immediately commenting with “This is too complicated,” a better approach would be: “I’m noticing some complexity in this function. Could we discuss the rationale behind the current implementation and perhaps explore ways to simplify it while maintaining functionality? Perhaps refactoring into smaller, more testable units might be beneficial.” This phrasing demonstrates awareness of potential issues without directly criticizing the author’s choices. Similarly, when receiving a PR, a response like “I’m not entirely clear on the decision to use this pattern here – could you elaborate on why it was chosen over [alternative approach]?” is far more constructive than simply rejecting the changes. It signals that you’re engaging with the reasoning behind the code and open to learning.

Another key element is acknowledging your own potential misunderstanding. Phrases like “I’m not sure I fully grasp…” or “Could you elaborate on…?” are invaluable tools. They demonstrate humility and a genuine desire for understanding, fostering a more collaborative environment. Don’t be afraid to admit that something isn’t immediately clear; it’s far better than proceeding based on incomplete information. This is especially important when discussing architectural decisions – often these involve complex trade-offs.

Finally, remember the importance of framing your feedback as suggestions rather than directives. Instead of “You should do this,” try “I was wondering if we could consider…” or “It might be worth investigating…”. This approach promotes a spirit of collaboration and avoids creating defensiveness.

# Example: Using `grep` to find potential inconsistencies in code
grep -rn "unused_variable" .

This command, using grep, demonstrates how you might phrase a technical observation – “I’m seeing an unused variable” – which could be the starting point for further discussion about potential refactoring. It’s less confrontational than directly pointing out the issue and allows the team to collaboratively explore solutions.