What Makes a Good DSL?
A good DSL -- one that helps the people who are using it -- makes it easy to clearly represent information for a particular purpose. The following are some characteristics of a good DSL:
- Well-defined scope. There is an easy-to-state single purpose for the DSL -- for example, "to describe the permitted sequence of states of issues in a project."
- Minimality. There are no more concepts and relationships than are required for the ideas that need to be described with the DSL. If you can see a way to reduce the number without losing information, do so.
- Familiarity. If there is a notation already in use in the domain -- railroad tracks? electrical circuits? -- base your notation on that. If the type of information is normally associated with a particular style of diagram -- statecharts -- use the conventions familiar there. Adapt the notation where you need to.
- Bring out the important bits. The most important things should be the most obvious and easiest to change: names of states, transitions between them. Less important detail -- for example, the target namespace of the generated code -- can be left to the properties window. If you need to print out the full detail for some reviews, write a report template.
- Moderate amount of redundancy. Ensure that when the user has made an important distinction, it was intentional. For example, we flag an error if the user has not marked a state with no incoming transitions as "start." On the other hand, users don't like to have to say everything twice, so don't overdo it.
- Use the syntactic space. Most of the diagrams a user can draw should be meaningful. A language that is heavy with complex constraints probably doesn't fit the conceptual space well and is difficult to remember how to use. The big advantage of a DSL is that the notation guides you through useful things to say.
- Graphs are not syntax trees. If you have an existing text notation, it is unlikely that its syntax tree will be the best graphical notation. See the example on regular expressions in the next section.
- Allow for customization. Your DSL will not cover all the cases that users will require. Provide for further customization through handwritten code, preferably without forcing the users to alter generating templates.
- Use the users' language. The language should be expressed in its users' terms, talking about their requirements -- rather than its implementations. Talk about issues rather than tables. Where it's difficult to avoid bringing in some implementation concerns, try to package them up in a single domain class, or by exploiting categories in the properties window. For example, in the DSL designer you'll find that properties that are mostly concerned with the form of the generated code are always gathered together under a "Code" category.
To illustrate the last few points further, we will consider the development of a different example.
