Nomenclature
In manufacturing components we deal a lot with names and naming. In one sense, it's a very powerful process that is akin to magic. I create a chunk of code that performs a task and I associate a name with that code and with little more effort than the act of communicating that name (typing it into a new application), that task happens.
I think of it like playing the game
Zork or similar text-based adventure game. If a text-based adventure was done poorly,
the game trained you the player to interact with it and required that you learn its vocabulary. If you didn't know all the verbs you'd spend a lot of your time guessing what sort of things you could try to do. If the game had been extensively play-tested, the authors usually put in humorous responses for outrageous things you might try. This is nothing more than a consolation for poor game design.
I have the same issue when writing code or designing an interface. I really don't want to make my clients guess what I called something or why. So the first guideline for naming something is that it should be obvious. Programmers are clever people, but cleverness just comes off as being smug and annoying when you're on the client side of an API.
I had a friend,
Jim Blandy, who had been porting some code written by
Rob Pike and completely out of coding context, he asked me "What's a rasp?" I answered the question from a physical perspective, "It's like a file but with holes in it". Then he explained what he had just gone through. He had a data structure and some surrounding code that implemented a sparse file model which was largely undocumented. The data type was parallel to the unix FILE structure except that it was called RASP. Unfortunately, unless you take it out of context, it's not immediately obvious that it's a FILE with holes in it. RASP is a bad name.
I tend to get very wordy in names these days, probably too much so, but I want the name to be able to express what is going to happen as clearly as possible. I will gladly sacrifice brevity for understandability. If you're typing a lot, remember that IntelliSense is your friend.
Beyond the immediate name is the surrounding fucntionality. If you have names that connote opposites, use natural opposite names: up/down, high/low, near/far, clean/dirty, acquire/release and so on.
When organizing classes, be consistent in the naming patterns. For our ImageSource class, which is the base class, we put the qualifier in front of ImageSource, so we get RandomAccessImageSource and FileSystemImageSource. Although some people prefer to have the name first and the qualifier second to take advantage of alphabetical order display so that related classes are close to each other, I prefer the more natural reading of it. My take is that you're going to use a class far more than you're going to look for it, so the ease in usage to prevail, and easy reading code is easier to use.
Here's an example that had me scratching my head the other day. There are many
wine bottle sizes that are available. My favorite, I think, is the Nebuchadnezzar, which is just a great name for something huge and daunting. Unfortunately, if you look over this chart, you'll find that some of the names don't exist for certain types of wines or their region or the size is different. A Jeroboam from Bordeaux is not the same as a Jeroboam of Champagne. Imagine my consternation when I came across
this at my local purveyor of potent potables. It's a 3L bottle which would be a double magnum of Bordeaux but a Jeroboam of Champagne or burgundy. I sent off this email to Stone Brewing:
I saw a nice little bottle of Oaked Arrogant *** at my local store and was curious if you consider the bottle to be a Jeroboam (name used for sparkling wines) or a Double Magnum (named used for non-sparkling wines), or just a big-ass bottle.
and I got the following response:
Steve, thanks for the email and the kind words about our beers. We never get tired of hearing from the people out there that are passionate enough about our beers that they take the time to write and tell us how they feel...and ask good questions.
Yeah, we haven't really thought about the name of that bottle. It could be called a Magnum, or Double Magnum, but could not be called a Jeroboam once it is filled with beer. However, to make it simple we might adopt your definition that fits it quite well: Big-Ass Bottle!
We really appreciate the support and keep on spreading the words of Stone and the Arrogance!!
Not as definitive as I'd like, but I appreciate that they took the time to respond to me.