The Tiny Detail And The Groggy Whole
In this post I’m jotting down some spontaneous thoughts about the importance of designing adequate software interfaces, kindof.
When you design a program for an end user, the user interface is what the user sees on the screen. When you design a library, the user interface is how a user (that is, another programmer) invokes your library code. In either case, how you design your UI matters a lot.
Especially in the latter case, details can make much of a difference whether your “UI” design is future-proof or not. I just came across an example worth improving upon, in a prominent library: Alex Gorbatchev’s SyntaxHighlighter.1
When I was reading about the configuration, I noticed the bloggerMode parameter: If you are hosted on blogger.com, you need to set it to true. Apparently there is a special “hack” for that case in the software.
My mind immediately rang the alarm bell: And what if I was hosted on, say, LiveJournal, and needed another special hack there? Would there be a liveJournalMode parameter in the future? And then, what if I set both to true?
Alternatives?
Instead of bloggerMode: true, why not use specialMode: 'blogger'? It would not only be a more natural way to express the intention, it would also be more open to future extensions like support for specialMode: ‘live journal’ (or whatever).
This may seem like a detail too small to be of importance, but in general, software applications are full of internal interfaces, and even small inadequacies quickly add up to a groggy whole. Or as Bruce Lee said in one of his films: They are weak, but they are many. 
- Alex Gorbatchev’s Syntax Highlighter is an excellent piece of code. This post is by no means intended as a critique on the library as a whole. [↩]
