I recently started hosting AMA-style cafe chats with developers at various stages of their journey, about software engineering and anything else within my technical experience. Below are some rough & rapid-fire notes from the chat on Oct 21st, 2022.

“I never did any formal design, where can I start?”

A dead-easy yet high-return strategy: take a core functionality of the system (e.g. “purchasing an item”) and jot down all facts that must be true for it to work as intended. Examples:

• “an item has id: string, name: string, and stock: number fields”
• “items are stored in a database table”
• “the list of items is exposed via the /api/items REST endpoint”
• “when an item is purchased, the stock field is decreased”

Don’t worry about mixing abstraction levels; better have them all mixed than get sidetracked into the problem of how to arrange such a document and give up.

Bonus #1: rules can be reused as test descriptions for various kinds of tests ^[1]. Examples:

• “when user orders item, logistics service is notified” → e2e
• “when button is clicked, API request is sent” → integration
• “item to cart data structure updates total figure” → unit

Bonus #2: in a cross-functional team, the list helps to keep alignment with product owners and business analysts; it’s easier for them to look at higher-level rules and say “that’s right” or “that’s wrong” than clicking around in the live application until something feels off. ^[2]

Informal diagrams are plagued by ambiguity. Want to draw boxes and arrows? Go for it, but keep asking: “In how many ways can this be interpreted?” If the answer is anything but “one”, keep working on it. Example:

[Service A] ---(item)---> [Service B]

Does the arrow mean “sends to?” or “request from?” or “responds with after being requested?”

Mitigate by religiously labeling every edge with verbs:

[Service A] ---(requests item from)---> [Service B]

When you’re ready for formal diagrams, start with sequence diagrams. They’re likely to serve you well for a long time, being high on expressiveness (they capture the flow of time along with various modalities of communication) and low on ambiguity.

---

1. And that’s not a coincidence. ↩︎

2. Good formalisms tend to do that. There’s a great anecdote in Harel’s paper about the development of state charts: in the midst of one of the sessions at the IAI the blackboard contained a rather complicated statechart that specified the intricate behavior of some portion of the Lavi avionics system. […] There was a knock on the door and in came one of the air force pilots from the headquarters of the project. He was a member of the “customer” requirements team, so he knew all about the intended aircraft (and eventually he would probably be able to fly one pretty easily too…), was smart and intelligent, but he had never seen a state machine or a state diagram before, not to mention a statechart. He stared for a moment at this picture on the blackboard, with its complicated mess of blobs, blobs inside other blobs, colored arrows splitting and merging, etc., and asked “What’s that?” One of the members of the team said “Oh, that’s the behavior of the so-and-so part of the system, and, by the way, these rounded rectangles are states, and the arrows are transitions between states”. And that was all that was said. The pilot stood there studying the blackboard for a minute or two, and then said, “I think you have a mistake down here, this arrow should go over here.” ↩︎