Let’s train our brains to cross some domains! If you don’t know what a CDKT is please read here.
This is a CDKT for 7 Fatal Mistakes of Naming in System Component Design.
Enterprise
Sales and Marketing vs. Customer Acquisition – this is very debatable, but look at it like this, both sales and marketing have the same end goal, to bring customers to our business. And they work directly with our customers, why should they be separate units with different management? It will require the company to do additional goals of aligning strategies, tactics, and actions of those two units to produce cohesive output. Naming and combining those two into a single department with a single goal removes that need for additional alignment entirely.
System
Finance vs. Billing – when we call something Finance it’s very hard (using noun-discrimination method), to put limited things inside such a system. On the other hand, Billing is more specific and we can draw a much more tangible line between what is Billing and what is not.
Component
Search vs. Contact Search – if we need to create a search engine in our app, we can just call it a Search, and all queries would be passed through it. This looks nice, Single Responsibility is good after all. But look closely at the change drivers for this component. Everything that needs to be searched impacts our search component. Is that bad? Well. There are two parts to that solution. First is the search engine which is universal, and can be used to index everything. The second part is the usage of that engine in the given context. And naming explicitly that we mean a contact search component that may internally use our search library/service, will provide us with a much more manageable solution.
Class
Order vs. Shipment – when we call something Order, and we stick to that name, this class will probably need to handle Shipment as well. The shipping of stuff has different requirements, like the number of packages, delivery schedule, and so on. Such things should not be a part of an Order. Remember to change the name if necessary.
Method
isAuthorized vs verifyAuthorization – if inside isAuthorized method we check and then raise some kind of error instead of returning boolean, our clients, other developers (yes, that also includes YOU after about 6 months) will be very surprised.
Class Field
User.history vs User.authenticatonAuditTrail – when we create a field named history, then what is stopping us from putting the history of failed login attempts alongside purchase history in that field? After all, purchases are a part of users’ interactions with the system. We need to be careful about what we want to be stored where.
Environments
PPE vs. R1-Staging – environments can have different roles in different stages of a project and between different projects for the same codebase. Try to name them accordingly. If you name an env a Pre Production Environment, and then start using this environment as a staging environment for new development (because let’s be honest that’s the only env that has anything working in it), then you harm yourself and others. Don’t change the roles of environments that have THEIR ROLE IN THEIR NAME.
Machines/VMs/Pods
srv-1 vs. myapp-web – names may not matter that much when you name your machines/vms/pods when everything is peachy. But if hell breaks loose you need a way to find out who’s who. Better to use descriptive disambiguate names, or labels, it depends on how you access them.
Project responsibilities naming
Solution Architect vs. Database Architect – that is an interesting one. Because having too many “Architects” in your project will create lots of confusion. I would not expose a Database Architect directly to developers (yes, that’s to protect the developers 😉 ), let him work closely with a Solution Architect, then there is at least a chance of creating a complete and cohesive solution. This also regards all other architect types, just define a hierarchy and stick to it.
Security Roles
Admin vs. Approver – not every role that can do more in your application than an ordinal user is an Admin role. You end up layering Admins: SuperAdmin, MasterAdmin. Try to find and identify what is the reason for this new role, give it a functional name.
API Endpoint
/workers vs /allWorkers – We need to tune in to what is the message here. So why /workers endpoint does not return every worker, but only those that have a valid contract? Where is this assumption communicated? If you plan to define what this noun (a worker) means in that system, be careful that it is communicated to the outside world, otherwise, you will need to create ugly additional endpoints like allWorkers just to fill in the gaps because different contexts have a different meaning for the same nouns.
DTO
Customer vs. Purchase History – when we expose a Customer object from our codebase again it will be hard to argue if his purchase history is a part of this DTO or not. Instead, we should focus on more explicit names and data sets.
Epic
Reports vs. Failed login attempts report – Again if you name an Epic as Reports/Reporting then during refinement sessions or design sessions or even in the production phase it will create a lot of confusion. This is a big basket. Lots of features and activities can be labeled as reporting, and they should! But you’ve just created an ever-growing unmanageable scratchpad for everyone. Complexity has to also be managed outside of the software, in the development process itself.
Story
As a user, I want to be notified about any issues in the system vs. As a user, I want to be notified about any unauthorized access attempts – remember the Epic example of ever-growing never-ending bags of wishes? Yes, the first one is like that. Be careful what you wish for in your stories, not that you may get it, but that they may never end.
Acceptance criteria
The solution needs to be secure vs. The solution needs to be compliant with regulatory requirements (OWASP, HIPAA) – there is no such thing as just a secure system. Security is a process. A process of making sure that things behave as they should even if something unexpected happens. And If you say you want to have a secure system, you won’t see one, and you will have a series of very sad meetings ahead of you.
Processes
Hire vs. Subcontractor Hire – If you name a process hiring, then my friend you just sentenced yourself to an ever-growing agonizing condition hell. There are different processes and steps to be taken, things to be considered, and risks to be managed if you hire a standard worker then when you hire a subcontractor. But since you have a hiring process then every egg will be put inside one basket.
Test scenarios
System security vs. User authentication – the world of big baskets is making yet another circle. The security is too big a bag. You will end up with lots of tests, and probably none of them will be the one you wanted.
Test cases
Failed login attempt vs. User login with invalid credentials – In the first case, we present only part of the picture, what are the reasons for this failed login attempt? How can we be sure we didn’t miss any crucial security test cases?
Use cases
Notify user about invalid purchase vs. Notify user when a purchased item is out of stock – Again in the first case, we create a very vast space with multiple things that can be classified as invalid purchases. We risk missing some crucial cases, and we created a way for never-ending discussions and scope creep, destroying the vision and understanding of the system.
DB tables
Survey vs. Survey Draft – when we store a valid survey definition alongside its draft, we can because it’s just a status change isn’t it? We create a table that not only has all fields optional to handle the drafting process, it also stores more data than it should and validates the basic assumption that when I look inside the Surveys table I will see Surveys.
DB columns
Active vs. Status – We need to recognize if a given entity is active or not. Then the boolean column suits us. But the moment we want to react differently to when the user is no longer active or has not yet been activated, we would likely overuse our Active column, and add a true/false/null value, and if the need for deeper differentiation arrives then what? Remember to change the name when needed.
Http param names
effective vs. effective_date – if you expose an API in a time-effective system, with a parameter of type: string and name: effective, be sure that you’ll have some questions to answer. All this confusion can be greatly reduced when we stick to being more explicit in our naming. Plus some examples of course, because not everybody everywhere will have access to API specification, especially when he’ll be working on generated DTOs.
Feature names
Lock User vs. Disable Authentication Methods – both of those features will achieve the same results. The user won’t be able to log in. But the first one, immediately screams: “there is a new type of user: LOCKED” while the other does not. The second one allows it to remain in a security-related domain. If it should or should not that’s a different topic, and as always it depends on your requirements.
Unit test case names
shouldNotAddUser vs. shouldThrowUserAlreadyExsitsException – in the first case you will encounter a code that just checks if the operation failed, for whatever reason. And where is the contract? How can I be sure that it works the way I want it to work? We need to check If we’re telling the whole story of what will happen or only the common part, namely that it won’t happen.
Exception names
IllegalStateException vs. PackageAlreadySentException – need I say more?
DDD Aggregates
User vs. Registration – in the first case your Aggregate will have a lot of dumb work to do, which is status-based validations. If not yet approved then you won’t be able to login or make a purchase or whatever. You will mix two different responsibilities. Managing the process of registration and managing user-related actions in one single class. This will be painful.
Summary
If you liked the idea of CDKT then please let me know. If you have any questions or ideas drop me a message. As always If you like more subscribe to my newsletter.