ZeroMQ

Contracts Are Hard

Writing contracts is perhaps the most difficult part of large-scale architecture. With unprotocols, we remove as much of the unnecessary friction as possible. What remains is still a hard set of problems to solve. A good contract (be it an API, a protocol, or a rental agreement) has to be simple, unambiguous, technically sound, and easy to enforce.

Like any technical skill, it’s something you have to learn and practice. There are a series of specifications on the ØMQ RFC site, which are worth reading and using as a basis for your own specifications when you find yourself in need.

I’ll try to summarize what I’ve learned from my experience as a protocol writer:

• Start simple, and develop your specifications step-by-step. Don’t solve problems you don’t have in front of you.

• Use very clear and consistent language. A protocol may often break down into commands and fields; use clear, short names for these entities.

• Try to avoid inventing concepts. Reuse anything you can from existing specifications. Use terminology that is obvious and clear to your audience.

• Make nothing for which you cannot demonstrate an immediate need. Your specification solves problems; it does not provide features. Make the simplest plausible solution for each problem that you identify.

• Implement your protocol as you build it, so that you are aware of the technical consequences of each choice. Use a language that makes it hard (like C) and not one that makes it easy (like Python).

• Test your specification ...