Monday, December 19, 2005
A Composition for Two Audiences
Your fellow developers are this audience, your clients can be this audience and, most definitely, you are this audience in the first place.
We have always implicitly acknowledged that we have to read back our own programs, even while we write them and this pushed us to create higher level languages that chunked together patterns of lower level operations. However, as this would have been enough to tackle the task at hand in an effective way, this was not enough to communicate effectively the intent of the code to other developers or even to yourself after a few weeks without having looked at the code.
That's when developers started using subtitles. You had bits of English interleaved with chunks of machine-friendly code. While this gave us some indications on where we were in the code-city this was not very useful to draw paths across the code and relate different sections of code together.
The use of comments could be augmented by following a number of conventions and rules that disciplined the code back to more manageable chunks of human understandable meaning. Meaningful names for variables. Advanced variable declarations. Elimination of gotos in favour of structured programming, and so on.
In this past few years, with extreme programming and ruby scrambling the rules of the game, we have come to appreciate expressive programming. The code says what it means, so that the code can also act as documentation for itself. We have seen this trend starting with java docs and embedded auto-generated documentation, evolving to the self-explanatory code of xp and the domain-specific-language practices of ruby.
As we have moved away from the early ideas of communicating via comments and we have embraced the idea that code should be written in such a way that it communicates to people, we have found ourselves shaping code that must please two audiences.
How easy is that to do? If you think it's easy I challenge you to this little "boomerang translation" game. Go on google tools for languages or on any other multilingual translation engine. Write a simple sentence in your native language and then translate it to one or more target languages. Now get those resulting translations and translate them back to your native language. How much meaning has been lost? How much of it has been distorted? Now, the challenge is to re-write the original sentence in such a way that it still makes sense in your original language *and* it survives the double translation keeping its meaning intact as well.
Trust me this is no easy task. You will find yourself twisting the language so that you can pack different shades of meaning in a single sentence, so that at least one will be preserved. You will come up with conventions such as brackets, hyphens or slashes to chunk together similar meanings.
For example, if you want to express the simple concept of "This afternoon I will catch the bus to go home", you will probably need to come up with something like:
"Today Afternoon I want to (catch / use / take) the ( bus / public transportation ) to go home"
You needed to disambiguate the word "will" that in this case declined the verb to the future, but that an automated interpreter could translate as "willpower". Also "catching" is kind of ambiguous since you don't really "catch" a bus, you just walk in it. To avoid further ambiguities you specify a whole range of meanings "(catch / use / take)". You would also soon realize that the word 'bus' can also have the further meaning of conduit and if you want to avoid translations such as "Here afternoon I deliberation to grab a conduit to go home" you will have to painstakingly check, disambiguate and provide alternatives for every little piece of meaning.
You will also need to go through several translation iterations to decide what works and what doesn't.
That's a good approximation of how it feels to write for two audiences, one made of humans and the other consisting of an automated unforgiving interpreter.