Warning: This can conceivably be viewed as a rant. However, I fall into the same traps as those I outline here, and I’m simply trying to organize my thoughts into a pattern rule that I can use when writing and maintaining my own code.
This post may have implications beyond programming. If you’re making forms for others to use, even if they’re not electronic, you’re defining an organized perspective on something. Organized perspectives are tricky, because they’re usually desperately needed in order to get ad-hoc notes, data, and relationships into some sort of structure so that useful information can be extracted.
Why should anyone care? Because when you start to interact with other people, forms, databases, or even excel spreadsheets, every concept and word you used in defining your data must be mapped to concepts and words in the other person’s vocabulary. Additionally, many words that programmers typically use are delightfully ambiguous. Programmers sometimes call this “flexibility.” Is this a misnomer? You can be the judge.
Here are some “flexible” concepts that are programmer favorites. Type. Reference. Category. Number. Name. Date. Item. Object. Context. It truly doesn’t seem too bad at first glance, right? After all, we used these words all through our CS degrees, and they’re sprinkled through all the writing and documentation that programmers do and read. Well, imagine coming across a data store (database, excel spreadsheet, whatever) with a table called ReferenceTypeNumber. Or CategoryTypeNumber. Or ObjectReferenceCategoryTypeID. Does that seem like an unlikely scenario? Trust me, it’s not.
And then there are the completely made-up words and concepts that programmers and data people made up, because they started confusing themselves. For example, let’s look at the concept of a “namespace.” A namespace is really a way of saying that you’re about to use all sorts of “flexible” names, and you expect that the names are so useful and good that someone else is bound to use them as well. You don’t want to confuse your “Type” with someone else’s “Type”, so you make a “namespace” and stick it at the front of all your words. My namespace might be “Gordon”. That would make my “Type” “Gordon”.”Type”. Your type might be “Jimbo”.”Type”, and we all live happily ever after.
Until you have to explain the concept of namespaces to someone else. Because when programmers finally “get” a concept, it means that we’ve managed to wrap their “flexible” concepts in their own brain around this new concept, and in order for us to tell you what it means, we use all sorts of “flexible” terms. And god help you, too, if you encounter XML namespaces and paste in the URI to your browser, find nothing, and become completely mystified.
“Oh, the User Type? It’s just the category of User. No, it doesn’t have anything to do with your LDAP User Type, or Active Directory User Type, it’s just your Website User Type.”
Dur.
So what, am I just complaining? Nope. I think it’s possible for programmers to think in tangible, real-world terms at the very least, when they interface with the outside world. Of course, it’s not practical to expect that Java / OOP languages change their base class from Object, because we need that “flexible” concept to even implement OOP. Luckily, non-programmers never need to be exposed to those concepts if we (the programmers) are careful.
The basic idea is this:
Name Carefully!
This is most useful for API’s, interfaces, documentation, communication, presentations, etc. If you get more comfortable and used to naming carefully, you can extend it further. Personally, I like to go as far down as I can possibly go, naming tables and fields in my databases carefully. I’ve had enough nightmares of discovery going through undocumented databases for two lifetimes. I try to extend a small favor to posterity by carefully naming and documenting my databases.
Now that i’ve explained the motive and the concept, here are some concrete processes you can follow to carefully name your own programming (or other) projects.
- When designing automation or databases around a flat-file or paper database, or even a “social” database of ad-hoc discussions, take detailed notes about the words people use in conversation about the concepts. If you can, create a glossary. The glossary of terms is a good place to start your naming conventions.
- Often, you’ll find that real-world humans use “context” as their “namespaces” in everday conversation. What does that mean? For example, if your context is a discussion about the company website, you can take “Account” to mean the credentials you log into a website with. In other instances, if you’re talking about customers, “Account” might mean an actual monetary account held with your company. In the examples, the context was different, so the same word held multiple meanings. We, as programmers, get confused too, so sometimes it’s useful to ask questions like, “Do you mean the Website Account, or the Monetary Account?” to enumerate the namespaces that you infer from the conversational context. Make sure to make notes of these contexts, because you might end up using them as namespaces, table names, or prefixes in your interfaces and forms.
- Make sure to review the glossary with the future users, and continue to refine it to minimize confusion or ambiguity. You know you’ve got the right terms when you can ask detailed questions clarifying your understanding, and you get detailed corrections or an affirmative response. Note: Many programmers are so used to getting blank stares when asking detailed questions, that they may be shocked at the improvement in feedback when properly using careful names.
- Try to use physical or tangible constructs that really fit well with underlying concepts. Instead of “Type,” some tangible constructs might be “Department,” “Clearance Level,” “Audience,” etc.
- If you’re not familiar with Database Normalization techniques, they can be invaluable in designing databases for maximum usefulness and extensibility. Creating a carefully-named system goes hand-in-hand with ensuring database normalization, because it helps you avoid overloading a table with uncorrelated records.
- It can be frustrating work! Make sure to take a break once in a while and talk like a normal person again. It’s good to be detail oriented, but it does get tiring after a while.
Many thanks to all those people who have inspired this way of thinking – John Coanda in particular (the most detail oriented guy I ever met, who showed by example how to carefully construct detailed questions about confusing topics).
Uncategorized
It looks like it does single-party management, with categorization, list of eateries by last access (a point of argument on eatlunch.at), and automated emails. This one actually does a final email that’s supposed to be authoritative at 11:00 am (more on that later) – Found as the #1 result for ‘vote for lunch’ on google.