In the Beginning was the Naming Convention

by Sean McGrath

November 18, 2005 —

I am a big believer in the humble concept of a naming convention as step one in solving any business problem with technology. As I see it, clear communications between the creators and users is a necessary, but not sufficient, pre-condition to the creation of any useful IT system.

Now being absolutely precise about the meaning of the terms/phrases used in any non-trivial problem domain is hard. Really hard. Perhaps even impossible. Things mean what they mean at a particular time, in a particular business context, in a particular business culture. Meaning is most often expressed through language - itself a notorious carrier of ambiguity. From these inauspiciously vague beginnings, meaning then proceeds to change constantly under our feet.

Pinning down the terms/phrases we want to agree on is like nailing jellyfish to bicycles. It is difficult to do, provokes strong reactions and leads to some pretty surreal moments. Our putative shared understanding is like a flotilla of wine bottle corks, bobbing on the turbulent seas. Sometimes we see them clearly, other times they disappear from view. Who knows where they have moved to now?

We do not spend our days conscious of this constant semantic shift underlying our terminology however. That is one of the great tragedies of human communication - unless you are a poet. We fill meeting rooms with people who are all using the same terms/phrases. Heads nod violently in assent or shake violently in dissent, often because parties have different interpretations of key terms/phrases in the problem domain. Consensus, when it is achieved, is awkwardly contingent. Contingent on the interpretation of what was supposedly agreed. It is a wonder we get anything done really. Yet we do. Thank heavens for probability and perseverance.

It is into this negative assessment of the IT landscape that I want to wade with the concept of a naming convention. I typically introduce these things in order to establish shared meaning in a group of people. In reality, I am not doing that. I am simply trying to agree to a set of terms/phrases over which we will most likely have differing interpretations. It is not so much a question of solving the interpretation problem as bounding it. A problem caged is a problem halved.

Whenever I work on a web project, naming conventions are never far from my mind. The Web (if you do it properly[1]) has a way of guiding you towards thinking in terms of naming conventions. What is a set of URLs other than a naming convention? What is HTTP other than a protocol that allows you to retrieve and update things according to an agreed naming convention?

There must be more to it than that. I am missing something. No, I am not setting up an "aha moment" ending to this article. I genuinely am missing something here.

You see, 10 seconds after I got my head around URLs and HTTP, the naming convention zealot in me took hold. 'It is only a matter of time', I remember saying to myself, 'before we have a naming convention for browsing database tables, executing SQL queries, updating calendars, tracking orders'. In my mind's eye I was envisaging naming conventions like these:

Browsing a database table:

http://www.example.com/database/tables/orders?by_date

Executing an SQL query:

http://www.example.com/database/sql/select

* from foo where bar = baz

Examining a day in a calendar:

http://www.example.com/calendar/2005/11/01/

Tracking an order based on its ID number:

http://www.example.com/orders/IDs/123456789

Instead, we have custom applications with custom APIs to do this sort of thing. We have very little in the way of naming conventions.

This surprises me greatly. I have clearly missed something significant. If you have figured out what it is, I would sure like to hear from you.

[1] http://www.xfront.com/REST-Web-Services.html

ITworld.com