When I write a program, what I’m essentially doing is writing down my best understanding of how to solve a problem or accomplish a task. My best understanding.
For the sake of this discussion, let’s say the problem I’m trying to solve is how to best peel an orange for eating.
An interesting thing happens, though, when I spend hours and hours talking about the problem, thinking about it, drawing diagrams of it on the whiteboard, relating it to other problems I’m familiar with, and coding it: I begin to understand the solution better. But not only that, I begin to understand the problem and its entire domain better.
With this deeper understanding of the domain, comes more precise terminology. For example, in my study of orange peeling, I discover that when there is a breach in the skin, the juice squirts out when I put pressure on it. But when the skin is perfectly intact, the juice doesn’t squirt out; it kind of oozes out from all over. So I might call these spots on the orange “squirt points” and “ooze points” from now on. But as soon as someone new to the domain of orange peeling hears the phrase “squirt point”, that person probably won’t know what I mean.
To me, the same statement using the term “squirt point” is much clearer than the one that says “the points on the orange where juice tends to squirt out when pressure is applied to the skin, usually implying there is a breach in the skin”, even though they technically mean the same thing. Someone unfamiliar with the term, on the other hand, will probably think the exact opposite.
Yes, the term “squirt point” is a reference to this longer, more descriptive definition, and it can just about always be replaced by its definition without changing the meaning of a sentence. But the fact that I’m using the term has more information. It means that when I say “squirt point” over here, and “squirt point” over there, I’m referring to the same exact thing. What if over here I use the full definition inline, but over there, I use the full definition except I say “when pressure is applied to the orange” instead of “when pressure is applied to the skin”. Is that the same thing? Is it a mistake? Did the person who wrote it (whether that be another physical person, or me years ago) actually mean to write “skin”? On top of that, even if the full definition is used exactly alike in both places, it takes significantly more work for the human mind’s limited pattern matching ability to recognize that similarity, compared with the short term.
We have to be careful though. It’s not as simple as making a rule that says: everyone should always use the term.
What if there are thousands of terms specific to this domain? Does everyone seriously have to learn them all before writing a single thing about orange peeling? What if there is a similar concept that overlaps 90%? Should a new term be coined? Or should the original term be modified? Say I want to talk about the points on the orange that juice squirts out when pressure is applied after the skin is already peeled. It’s essentially the same as “squirt points”, where the orange’s skin is not present. If I know the term “squirt point”, then I will be tempted to use that term, slightly modified. But if I overload that term, essentially creating a new definition for it, I’ve just changed the meaning of every other thing that refers to it, whether that be pieces of writing, learning material, documentation, code references, project plans, issues, or even other people’s mental references to the term.
In the worst case, I could have just broken something, making what made sense before no longer make sense. Regardless, making the definition of a term more general implicitly makes everything that refers to it more complex, because in the more general version of “squirt point”, the fact that pressure is being apply to the skin is no longer contained within the term. So when relevant (which itself may not always be clear), things referring to “squirt point” now must also say whether the skin is present or not.
For those that haven’t already been doing this, I encourage you to imagine what happens with this discussion when you replace the word “term” with “function”, because this problem constantly arises when more than one person are involved in a software project. Because developers are literally writing down their understanding of the solution to the problem in code, the resulting software can only be as good as the developers’ understanding of the problem domain.
This means that if you are a developer, you should do everything in your power to understand everything about your problem domain. Not just the specific task at hand, but the big picture where it all fits in. Not just how to fulfill the requirements given to you, but what requirements were probably missed completely because the people writing the requirements have less understanding of certain domains related to software.
But this also means that if you are running a company, and you are not a developer, you should do everything in your power get the developers to understand everything about your problem domain — because the software that they produce, can only be as good as their understanding. If you simply give them requirements, they will do their best to interpret those requirements in the context of everything they understand (just like anyone else). That isn’t enough. There are 53.2 million ways to skin a cat. You won’t get the way that you want unless in addition to saying what you want, you also say why you want it. This is essential for a developer. Because every developer is a designer, whether they like it or not. They are constantly making decisions that affect the business as a whole. If developers don’t understand why end-users want a feature, for example, it’s likely they will misjudge the importance of the feature and make an unacceptable trade-off in the design process.
