[NOTE: The original version was posted in 2007 on an O'Reilly blog, but the page has been erroring out for months now. I'm copying it here because archive.org, while useful, can be slow. chromatic is a lovely person who (he thinks) probably has copyright to this piece.]
The "Is It a DSL or an API?" Ten Question Checklist
You can’t spend more than ten minutes at RailsConf without hearing the dreaded three-letter acronym DSL. They’re everywhere these days in the Rails and Ruby worlds. I think I ate one for lunch (either that, or it was a grilled portobello mushroom sandwich).
Confusingly, every example of a DSL I saw looked like something I would have called an API before my sudden immersive enlightenment.
If I’m confused about what a DSL is, you must be too. I took copious notes through the sessions on Friday and have devised a simple, ten-question test to help you determine whether a wad of code represents a DSL or an API.
- Have you ever programmed in a language other than Ruby? (PHP and HTML don’t count.) If not, it’s a DSL.
- Is the defining syntactic feature that you’ve cleverly left the parentheses off of a list of function arguments? If so, it’s a DSL.
- Is the code primarily a list of key-value pairs? Welcome to DSL Town, population you!
- Does the code require the liberal use of eval() or equivalent? DSL, yay!
- Have you ever used the phrase “… and it reads just like English!” in seriousness? You’d better get to the hospital; you’re coming down with a case of the DSLs!
- Are there colons on the front of otherwise-normal English nouns? Did it hurt when your DSL fell down from heaven?
- Is your code full of language-specific idioms, such as the placement of curly braces and the pipe characters? Smells like a DSL in here!
- Are examples of the code in question pervasive throughout your entire project rather than localized to particular sections in terms of encapsulation? Pardon me, I think you have a little DSL on you.
- Did you build your own parser and interpreter? Haha… oh wait, that might really be a DSL.
- Did you merely choose names for identifiers that match the language of the problem domain? Sorry buddy, that’s just an API. Try again next time!
In all seriousness, David Black’s argument is the only sane discussion I’ve seen of domain-specific language in all of Rubyville in about two years. Using the language of the domain of the problem which you intend to address is one excellent technique to producing software of high quality.
Slapping punctuation characters on barewords isn’t a sign of anything.
Update: Piers Cawley’s Domain-agnostic languages provides an excellent followup.