Programmer Musings

On Creative Class Names

The subject of naming in code continues.

In O'Reilly Network: Ill-monikered Variables and Creative Class Naming [May. 18, 2004], Tim O'Brien adds his comments to the topic of naming in programs. He picks up with Andy Lester's earlier comments and goes a little further.

O'Brien makes the suggestion that creative names are much better than mundane object names. His best example was the use of Bouncer instead of SecurityFilter. In some ways, I agree with him. The purpose of a name in code is to convey intent to the reader of the code. The computer doesn't care what you name things, but the next programmer to read it will depend on names to tell him/her what the code is intended to do.

That exposes the one problem I have with this suggestion. Each name you can choose brings with it more than just its definition. A class called Bouncer brings with it a host of subtle shadings of meaning. In his example, a Bouncer would check for valid ID and reject any request that fails this test. However, a real Bouncer is also often charged with throwing out rowdy customers even if their IDs were valid. A real Bouncer would also recognize troublemakers that have been problems before and deny them access, regardless of their IDs.

The problem with his suggested name is the extra responsibilities that are attached to it. Does the Bouncer object just check IDs? Or does it support monitoring activities? Does it have the ability to throw out disruptive requests, or support the ability to have a manager order it to bar a request for other reasons? Should the Bouncer class maintain a list of rejected clients in order to reject repeat offenders.

The problem with a creative name like this is that it may lead the reader to assume (consciously or not) that the class has abilities and responsibilities that it doesn't have. If the class does have multiple related responsibilities, a clever name can simplify understanding. But if the class has only one of the possible responsibilities, the name may cause more confusion than good.

I agree that many people writing code don't apply any imagination to the question of naming. However, some classes don't have creative names because the programmer wants to specifically limit the implied promise of the class's responsibilities.

Despite what I say above, I think that creative names are a very important tool for use in writing code. Coming up with the True Name for a class will make maintaining and using the class much easier as time goes by. But a clever name is not the same as a good name. Some really good names aren't clever, they are obvious. Some really clever names are useless. If the clever name already has an accepted meaning in the field, using it might cause more confusion than it is worth. As with everything else in this field, the tradeoffs are the key. When the creative name makes the code or concepts clearer, I'm all for it.

O'Brien's suggestion of using a thesaurus is a good one. Finding a good name with the right connotations can get all of the benefits that O'Brien suggests.

Choosing a name just because it might sound good to "management" (or whoever) won't be a good idea if that person makes an assumption, based on the name, that is not true. After all, if one Bouncer is a good idea, maybe we can employ two or three and then we don't need any other kind of security. Even better, the Bouncer will probably remember the troublemakers and not let them back in. Obviously, these kinds of assumptions could lead to very different expectations of what the software is expected to do.

The Fallacy of the One, True Way of Programming

What is it about programmers that cause them to latch onto one approach and try to apply it to every problem? Maybe it's a characteristic of people in general. Each new paradigm, methodology, or even language seems to grab hold of many programmers and make them forget anything they ever knew. They seem to develop an overwhelming need to re-implement and replace all that came before the new tool.

This isn't always a bad idea. Done deliberately, this technique can help you evaluate a new methodology or language by comparing the solution of a known problem with a previous solution of that problem. Unfortunately, many of us seem to assume that the new way is better and apply the new approach despite any evidence that it does not solve the problem more effectively.

Over time, I've come to the conclusion that there is no One, True Way of Programming. This is not my own insight. I have read this and heard this from numerous people with more experience. Earlier in my career, I did not believe them. I didn't disagree, I just didn't believe. Through experience with multiple paradigms, languages, and methodologies, I've finally come to understand what those senior people were trying to say.

Multiple paradigms are different tools in my bag of tricks. Each language is another tool that I can apply to a problem. Different methodologies give me different approaches to solving a problem. But, in the end, no single set of these tools can help me solve all problems. Each combination has strengths and weaknesses. One of the most important skills we can develop is the ability to recognise the right tool for the job.

Many years ago, I saw this point made in a book. (One day I'll remember which book.) The author pointed out that very different techniques and processes are needed when you are building a skyscraper and when you are building a doghouse. The author pointed out that the techniques that would be used to architect a skyscraper are not cost-effective when building a doghouse. I think I would now go a little further and suggest that the techniques are not appropriate, and that cost is one easy measure of why they are not appropriate.

Review of XML Bible

XML Bible
Elliotte Rusty Harold
IDG Books, 1999

As computer books go, this book is old. However, it does a spectacular job of handling all of the nitty-gritty details of XML. I first stumbled across this book when it was new. The only really definitive information you could find on XML was the W3C recommendation itself. This book does a very good job of explaining most aspects of the XML recommendation in a more conversational style.

Currently, most people who need to work with XML know (or believe they know) enough about it to work effectively. The W3C recommendation is still the place to go for definitive answers to clear up any confusion. But, if you need to be the expert, and you don't want to spend a lot of time reading the official version, this book will probably answer any question you have, without putting you to sleep.

Although the book is very complete on XML, it does not cover any of the more recent tools and specifications. This is understandable since it was written before they existed. In spite of that, I still highly recommend this book.

Review of XML in a Nutshell

XML in a Nutshell
Elliotte Rusty Harold and W. Scott Means
O'Reilly, 2001

This is a good overview of XML-based technologies as of 2001. If you are looking for a deep understanding of the uses of XML and related technologies, this is not the right book for you. However, if you are looking for a high-level overview or a book to refresh your memory, this is the book to read. It provides a good overview of the major technologies available, including XSLT, XPath, CSS, SAX, and others.

Unlike many books and articles I've read, this book looks at the two main philosophies of XML in a relatively dispassionate way. One section of the book is devoted to XML as documents, which they call Narrative-Centric Documents. Another section is devoted to XML as Data, which they call Data-Centric Documents.

Unlike many writers, I find many good uses for both approaches. This book treats both approaches equally and covers how some of the related technologies relate to each.

Flow and Miller's Magic Number

Recently, I stumbled across Mental State Called Flow and was reminded of an idea I had about flow and Miller's Magic Number. When in the state of flow, I've sometimes had the experience that the problem I was working on was much easier to understand than it seemed to be when I was not in flow. In observing and talking to other programmers, I've come to the conclusion that this is not an unusual experience.

Several years ago, I worked with a senior programmer who always seemed to be in flow (or hacking, depending on who you asked). Unfortunately, the code he wrote was often difficult to understand. After a few years, I made a breakthrough. I could usually understand his code while in a state of flow. While in flow, not only I could understand his code, I could also refactor it into a form that I (and others) could understand under normal circumstances. Other programmers in the group had similar experiences.

One day, everything seemed to come together in a blinding flash. During flow, Miller's Magic Number is larger. Normally this number appears to be around 7 chunks of information that you can deal with at one time. But during flow, the number of chunks seemed to be much higher. I have no idea how large the number is, but problems that seem to be at the edge of my ability normally are quite easy to deal with while in flow.

This means that flow can have a downside. If you are not careful with how you write the code, this larger number of information chunks will always be required in order to understand the code. You have probably seen this phenomenon in code that was written as part of a long hacking run. It usually works, sometimes even works very well. But you can't quite make sense of why it works like it does. This may be one of the reasons that hacking code has gotten such a bad name. Code like this is nearly impossible to maintain.

However, you can use this enhanced facility to understand the problem and still strive for simple, elegant code. The result is code that solves a difficult problem in an obvious way. Much of the time, this solution is only obvious in hindsight. You required more information while working on the problem than you normally could handle in order to see the simple and obvious solution.

In the Jargon File, the term hack mode is used to describe this form of flow that particularly focuses on The Problem. I believe the ability to use the benefits of the increased magic number, without making your code require this concentration to understand is one of the more important skills to learn in programming.

Update on Competence

In Programmer Musings: More Thoughts on Mastering Programming I referenced the four levels of competence without being able to remember the original source. According to Four Levels Of Competence, the source is the "Kirkpatrick Model" by Donald L. Kirkpatrick.

Idiomatic Programming

Like any natural language, most programming languages support idioms. According to the American Heritage Dictionary of the English Language, an idiom is

A speech form or an expression of a given language that is peculiar to itself grammatically or cannot be understood from the individual meanings of its elements, as in keep tabs on.

Programming idioms can, of course, be understood functionally from its individual elements. The interesting thing about most programming idioms is what they say to the programmers who will read the code later. A programming idiom can reveal many things about the author of the code. To some extent, the idioms you choose are a function of your understanding of the language, what you may have been taught in school, and the other languages you have programmed in.

I made a comment on this subject earlier in Textual Analysis and Idiomatic Perl on Perl Monks. In that article, I pointed out that idioms are cultural, just like those in natural languages. Also like in natural languages, if you only have experience in one culture and language, the idioms of another appear unnatural or wrong. When learning a language, you learn the syntax and obvious semantics. You have to live with the language for a long while to learn the idioms.

The result of this is that the idioms of a language are foreign to new speakers. As they continue to use the language, simple idioms become part of their vocabulary. At first, they will misuse or over-use these idioms. Over time, they develop an appreciation for the subtleties of the expression. Eventually, those idioms are only used when necessary. With more exposure, more idioms become assimilated into your vocabulary. Soon, you learn to speak/program the language relatively fluently. Also, like natural languages, you may always retain a bit of an accent, based on your earlier languages.

This explanation seems to explain the course I've seen many programmers, as well as myself, take with a new programming language.

1. You learn the basics.
2. You begin to recognize and fight against the idioms.
3. You slowly recognize the sense of simple idioms and try to use them.
4. You over-use the idioms you know.
5. You develop a reasonable understanding of those idioms and begin using them correctly.
6. You learn new idioms and go back to 4.
7. Eventually, you program with the language instead of fighting it.

The simpler the language, the quicker you get to the end of this cycle. But, a simpler language is not as expressive. So, you find yourself doing more work than should be necessary. A more expressive language takes longer to learn, but it's easier to pass on subtle shades of meaning to the maintenance programmer (possibly yourself).

This is not to say that you must use advanced idioms to be effective in a language. Sometimes, a simple expression is all that is warranted. But, complex ideas and complex problems often have subtle solutions. Subtle shades of expression can help the reader of your code recognize when they need to pay attention. In the example from my Perl Monks note, I talk about variations in intent expressed by different conditional expressions in Perl.

Idiom can also serve as a warning. An unusual or advanced idiom should tell the reader that he is entering dangerous territory. This is a message that it's time to pay close attention. A friend of mine is fond of referring to advanced code with the phrase Here there be dragons like on old maps. A properly placed idiom can do that more effectively than a comment. More importantly, if a good programmer runs into an new or unusual idiom, he should know to tread carefully and pay attention.

I think that idiomatic programming is a lot like becoming fluent in a natural language. You may be able to communicate with someone from Mexico using your high school Spanish. But going beyond simple, straight-forward communication will probably take a lot of effort. In some cases, that's enough. You can be mostly right when asking where is a restroom or how to find a taxi. But if you needed to argue a business or legal case or explain a medical condition, I'm sure you would want every possible nuance of the language at your disposal.

Programming is one of the most complex things that humans do. You have to be able to take complex concepts and translate them in such a way that they communicate to two very different audiences: an incredibly literal device and an intelligent person who may need to make subtle changes later. Explaining the instructions correctly to the computer is hard. Communicating your intent to the other programmer is even worse. If that programmer misunderstands your intent, he might ruin all of your carefully thought-out work. Well-chosen idioms can help in communicating that intent.