Use the same vocabulary for the same concept

Usage

📝 Guideline

Use the same vocabulary for the same concept: Avoid using different terms to refer to the same concept within your codebase. Pick one word per concept and stick with it.

By using consistent vocabulary for the same concept, you ensure clarity and maintainability in your codebase. When multiple terms are used to refer to the same concept, it can lead to confusion and make it harder for developers to understand and work with the code.

🛠️ How to Apply

• Choose a clear and descriptive term: Select a word that accurately represents the concept you want to convey. Make sure it is easily understandable and unambiguous. 📝
• Establish naming conventions: Define naming conventions and stick to them. Document the conventions to ensure everyone on your team follows them. 📋
• Refactor inconsistent code: Regularly review your codebase and identify instances where different terms are used for the same concept and refactor the code to use a single consistent vocabulary. 🔄
• Avoid unnecessary variations: Stick to a single term throughout your codebase to refer to the same concept. Avoid using synonyms or similar words that can cause confusion. 🚫
• Consider the context: Understand the domain and context of your code to select appropriate vocabulary. Use terms that are commonly used and understood within the relevant field. 🌍

Pros and Cons

👍 Pros

• Improved readability: Consistent vocabulary makes the code easier to read and understand by reducing confusion caused by varying terminology. 👓
• Enhanced maintainability: Using the same vocabulary simplifies maintenance tasks, as developers can quickly locate and update code related to a specific concept. 💪
• Efficient collaboration: Clear and consistent vocabulary fosters effective communication among team members, leading to smoother collaboration and reduced misunderstandings. 👥

👎 Cons

• Initial effort: Enforcing consistent vocabulary requires upfront effort to establish conventions and educate the development team. 👷‍♂️
• Lack of flexibility: Strict adherence to the same vocabulary may limit flexibility when new concepts or ideas emerge. It is important to evaluate the context and make necessary adjustments when needed. 🔄

Examples

❌ Bad

// Inconsistent vocabulary for the same concept
function calculateSum(a, b) {
  return a + b
}
 
function computeTotal(x, y) {
  return x + y
}

✅ Good

// Consistent vocabulary for the same concept
function calculateSum(a, b) {
  return a + b
}
 
function calculateTotal(x, y) {
  return x + y
}

References

🔀 Related principles

• Avoid ambiguous names: Clear and unambiguous names are closely related to using the same vocabulary for the same concept since both can introduce confusion with naming. 🔤
• Follow established conventions: Consistency in vocabulary is aligned with following established coding conventions and best practices.📖
• Don't overload method names: Overloading method names with different meanings violates the principle of using the same vocabulary for the same concept. ⚠️
• Descriptive and meaningful names: Choosing meaningful and descriptive names for code elements is closely related to using the same vocabulary for the same concept. 📚