5. Names Matter

Why Good Naming is Crucial

Naming is one of the hardest yet most important aspects of software development. Good names make code clear and understandable, while poor names create confusion and errors. That's why it's essential to pay close attention to naming variables, components, classes, files, and folders.

Every developer has been there—staring at a new variable or function and thinking, "I'll just call it data or temp and fix it later..." But later rarely comes. Before you know it, your team is working with processDataV2Final() or xyzHelper(), and no one actually knows what it does.

🔍 Why Names Matter

• ✅ Say what you mean – calculateTotalPrice() is better than doStuff().
• ✅ Avoid confusion – userList (a list) is not the same as userData (an object).
• ✅ Think of the reader – Your code is read more often than it is written.

🎯 How to Choose the Right Name

In my projects, I pay a lot of attention to naming, and I emphasize this during code reviews. When naming something, I always ask myself:

• ✅ Does this name fully reflect the functionality of the variable, class, or function?
• ✅ What terms does the client use? (But beware of jargon that doesn't make sense in a development context.)
• ✅ Does it align with existing APIs or systems?
• ✅ Is it immediately clear to another developer (or to my future self)?
• ✅ Could this name be ambiguous? (Avoid names with multiple interpretations.)
• ✅ Be specific but don't add unnecessary details – Context is key. A user's name could be stored as userName, but within a user object, just name is sufficient. Unnecessary information makes code longer and more complex.
• ✅ When in doubt, I always consult my team – Together, you often come up with better, more logical, and consistent names.

🚀 Good Naming is an Ongoing Process

As development progresses, insights and functionalities evolve. That's why it's important to regularly check whether names still accurately represent what they do. This prevents your codebase from becoming cluttered with misleading or outdated names.

🗣️ Share Chosen Names with the Entire Team

Naming isn't just a developer's concern. To avoid miscommunication, it's smart to align naming conventions with other team members, such as designers, UX specialists, and project managers. When everyone uses the same terms, collaboration becomes smoother, and communication is clearer.

📖 Document Naming Conventions

To ensure consistency, I always create a dictionary in the project's README.md, where we record chosen names. This is especially useful for project-specific terminology. It prevents different team members from using different names for the same concept. Sometimes, I even include translations if the client or external parties use different terms. This greatly improves communication and ensures that documentation, code, and discussions stay aligned.

⚠️ Common Pitfalls

• 🔹 Blindly adopting client jargon – The client knows their own terminology, but that doesn't mean it makes sense in a technical context.
• 🔹 Using texts from design or copy documents – UI texts change frequently during a project, but you don't want to refactor your code just because a copywriter updated a word.

🤝 Need Help with Naming?

Good naming leads to a consistent and maintainable codebase. So next time you name something, ask yourself: Is this name truly clear?

Need help finding the right names in your project? Feel free to reach out—I'm happy to help!

📌 This is part of my weekly series, Developers Tiles of Wisdom. Follow me for more insights on writing better code and building better teams.