It’s not a open to debate that English is the lingua franca of programming and that it’s good practice to use English in your code. It’s equally true that a sizeable majority of developers are non-native speakers of English, many of whom work on products intended for an exclusively local domain. By this I mean software that is used within a single country, like bespoke software for the Dutch tax office. Since English is not an official language in our country, are we allowed to use these Dutch domain concepts in our code or should we translate them?

The ubiquitous language

It all depends on the ubiquitous language that is already in place among stakeholders and end users. When most communication is already exclusively English — like in most scientific domains — translating them is obviously confusing and a waste of time. It’s a whole different game when there are no equivalent English terms for these common domain concepts because they refer to specific regulations or institutions. The fiscal and legal domains are rife with abbreviations of these concepts, that can have a pretty tight relationship to the software concepts that implement their logic. Actually it doesn’t even matter if you have a proper English translation for them: if it’s not common parlance among your specialist users it’s bound to add to the confusion.

I was reminded about software and human language after a recent project for a large Dutch insurance company (hint: they wisely used the proper Dutch terms in their code) and reading Kamil Nicieja’s excellent book Writing Great Specifications, in which he talks about polysemy and false cognates.

My theatre planning tool Kwinsie uses common terms from the theatrical domain that are so widespread everybody who’s ever been to a show will know them. The actor John plays the role of Claudius in all six performances of our production of Hamlet. The code started out with Actor, Role, Performance and Production classes.

Let’s now put on our software glasses and suddenly these four terms mean something very different: To increase performance in the production tier we’re moving to an actor system. Ouch. Should I rename my Actor object to Thespian? Or refactor Performance and Production to the Dutch Voorstelling and Productie? I’ll do neither, because I’m not worried that they cause confusion ‘Performance’ is a quality attribute and ‘production’ is a term from the deployment domain. They don’t occur in code as classes or variable names. Anyway I wasn’t happy with any of the alternatives for performance and production, but if there is a good alternative for a term that means exactly the same but doesn’t coincide with a software term, by all means choose that. Now if I were using an actor system like Akka in my code I would definitely consider calling the human Actors something else (Actress?) because the two are clearly false cognates and code populated by two completely different Actor types is confusing.

Roles and Parts

Here’s another one. Consider the term role: the user John is cast in the role of Hamlet, and he has the admin role for this production. Perfect confusion, because the meaning in the software and the theater domain coincide. Moreover, any software that authenticates users will encounter roles. You’d do well to disambiguate the two. Part is quite a good alternative (She acts the part!). Please leave the well-established authorisation role concept intact and don’t call it something like privilege. In the user-facing part of the application you’re free to use whatever terms you see fit, but be careful there as well when the interface allows you to assign acting roles as well as application roles.

Remember that human language, like the human body, is inherently messy and not designed up-front — at least that’s how I see it. So writing software should be about managing complexity and avoiding confusion, not about consistency at an price.