How to write a design doc: a short guide for junior developers
What a design document is for, a half-page template (components, data structures, trade-offs, open questions) and a worked example, before you write any code.
A design doc (or design note) is a short written plan for a piece of work, shared before the code. It exists to find mistakes while they cost a paragraph to fix instead of a week of rework.
A half-page template
- Components. The two to four pieces of the solution and what each one is responsible for.
- Data structures. What you store, in which container, and what each operation costs.
- Key decisions and trade-offs. What you chose, what you rejected, and why.
- Edge cases. The inputs and situations that need special care.
- Open questions. What you need someone else to decide.
That's it. No diagrams required, though a small one can help.
A worked example: an LRU cache
Ticket: "Cache product pages. At most N entries; drop the least recently used one when full. get and put must be O(1)."
Components. One class,
LruCache, with get, put and erase.Data structures. A
std::listof (key, value) pairs, most recently used at the front, and anstd::unordered_mapfrom key to the list node. The map finds an entry in O(1) on average; the list moves a node to the front (splice) and drops the back in O(1). List iterators stay valid when other nodes move, so the map's iterators never go stale.Trade-offs. A
std::mapwould keep keys sorted but costs O(log n) and doesn't track recency. Storing a timestamp per entry and scanning for the oldest would be O(n) per eviction.Edge cases. Capacity 0 stores nothing. Putting an existing key updates and refreshes it.
Open questions. Should stale prices expire? (Possible follow-up: a time-to-live.)
Notice how much the note decides: the complexity of every operation, the reason for each container, and one question for the product manager. More on picking containers in the guide to C++ containers.
Common mistakes
- Describing the code instead of the decisions. Line-by-line plans go stale; reasons don't.
- No alternatives. If you can't name what you rejected, you probably didn't consider it.
- Hiding uncertainty. Open questions are a strength, not a weakness.
Practise with a reference to compare against
Every Devventura project includes a design task: you write your note, then reveal a senior engineer's reference design to compare. Try it on the Quickcart product cache or room bookings for Meetly.
After the code is written, check it with our code review checklist.
Questions and answers
- How long should a design doc be?
- For a single feature, half a page to a page. Long enough to show the components, the data structures and the trade-offs; short enough that a reviewer reads it in five minutes.
- Do junior developers write design docs?
- Increasingly, yes, at least for their own features. Even when nobody asks, writing a short note before coding catches most design mistakes while they're still cheap to fix.
Practise it in a project
These projects put this guide to work, with tickets, tests and code review.
Quickcart
A product cache for Quickcart
Put a least-recently-used cache in front of Quickcart's slow product service, with O(1) operations, statistics and live resizing.
- hash maps
- linked lists
- iterator stability
- amortised O(1)
Meetly
Room bookings for Meetly
Stop double bookings in Meetly's rooms with an ordered index, then find times when everyone is free by merging calendars.
- half-open intervals
- ordered maps
- interval merging
- lower_bound
Gatekeep
Rate limiting for Gatekeep
Protect Gatekeep's customers from traffic floods with token buckets: exact integer refills, a testable clock, per-client limits and bounded memory.
- token buckets
- injected time
- integer arithmetic
- memory bounds
Read next
- How to work with tickets and acceptance criteria as a junior developer
How to read a ticket, find what it doesn't say, ask good questions, and turn acceptance criteria into tests, with examples from realistic product tickets.
- Code review checklist for junior developers
What senior engineers look for in a code review, as a practical checklist: correctness, edge cases, tests, naming, structure and performance, with C++-specific points.