
Ask HN: How do you write efficient and elegant systems / APIs? - julius_set
I have seen very elegant and efficient open source repositories.<p>Recently I had a few breakthroughs, where instead of searching for an answer from the bottom up, I visualized the solution from the top down. I imagined how I would access the API as another engineer and that helped a lot.<p>How does one improve their skill at making &#x2F; writing a more elegant and efficient system or architecture?
======
sethammons
I've heard it called Document Driven Design. Document how to use your API
first and get feedback from that.

I always design from the outside in. How do I imagine this API and flow to
work, and then how do I structure data and storage. Think of the developer
experience before you think of your experience as the implementor of the API.

~~~
howard941
This is also what I do. I like UML-ish diagrams to help communicate the ideas
with my cow-workers although I use it loosely, not following the formal specs
or even doing it electronically, just on paper, to diagram the interactions
and from there design my structures, state transitions, and message sequences.

The most serious problem I run into is keeping the documentation synchronized
with the project. For everything non-trivial it seems I always get to a point
where the project is so far from the docs that it's not worth going back to
update. Do you discard the documentation when you've built the thing?

~~~
sethammons
When I think document driven design, I think more along the lines of "api
spec" or giving the interfaces/method signatures. Sometimes this goes into
"boxes and arrows" stuff. For boxes and arrows, I usually don't go back and
update those. But for the API spec, example usage, etc, I prefer something
that is self documenting or has to be kept valid via tests. This is
particularly easy in a language like Go (what I tend to work in) as you get
GoDoc for free if you comment right, and you can have your examples directory
run with tests.

------
LiamPa
This is how I like to program, I find writing the readme first helps as I can
write the ideal/easiest way of using the code first as a user.

When it comes to writing code for the user Kenneth Reitz is the master in my
eyes.

[https://github.com/requests/requests](https://github.com/requests/requests)

------
thedevindevops
(Maybe a bit old-school?) But I try to model it as a console app, imagine what
commands I'd enter to achieve a result and they become the routes.

