HN Explorer

Ask HN: How do you write efficient and elegant systems / APIs?

19 points by julius_set ↗ HN
I have seen very elegant and efficient open source repositories.

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.

How does one improve their skill at making / writing a more elegant and efficient system or architecture?

7 comments

[ 3.4 ms ] story [ 26.5 ms ] thread
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.
julius_set
I would argue that DDD is not as efficient if your optimizing for speed and efficiency.

The problem is that there is now another variable you would need to keep track of: your UML diagrams / documents.

I guess creativity comes into play. For example if I am designing a video editing API. I could think bottom up and start from frames/buffers maybe. I might reason that I require a:

- Renderer - Singleton that is an editor which holds our sequences - Interfaces that can be exchanged for different types of editors - etc.

However the other approach is top down. Imagine how the ideal api looks like and go from there:

editor.addSequence(sequence) editor.process(item: [ .transaction(action: editAction), .transaction(action: saveAction), .transaction(action: finishAction) ]

^ so for example I might start from there and build the system from that point of view.

Anyways would appreciate more of a discussion here.

tcbasche
I second this when it comes to APIs. If you're exposing them to third parties it's especially useful, as you can draft how the endpoint should look and behave using something like Swagger, and then work from the top down. At my job we have close communication with third parties who use our api endpoints, so we are constantly sending drafts of JSON requests / URLs back and forth.
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

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.