Handmade Hero»Forums»Code
Jason
235 posts
Grapling with the ideas of writing the usage code first and compression oriented programming
Edited by Jason on Reason: Initial post
So I've been programming a side project (my own 2d fighter game) for a couple months now and throughout I've been trying to program in the way Casey has been teaching on his streams; by utilizing the ideas of 'writing the usage code first' and 'compression oriented programming'. However, I'm having trouble grasping how these concepts are suppose to work together when programming. I believe this comment Casey answered on stream helps to sum up my issue:

"You recently emphasized "Write the usage code first" and then the implementation later. While compression oriented programming is about writing code first and then compressing it, pulling code into functions where necessary, allowing the API to evolve out of that process. They seem like two contradictory methods. Are they? How do you decide when you're using one or the other?"

Basically, Casey said that when you don't know what it is your suppose to do and you don't have code in front of you, that's when you write the usage code first. When you do have code in front of you that's when you do compression oriented programming. But in my mind, when you didn't have any code in front of you and you're not even sure what it is you need to do, that should be when you just write the simplest thing that comes to mind and then your start abstracting out your api through compression oriented programming techniques. Of course, if things are done this way then what is the need of ever writing usage code first? since the api will just come about organically through the compression oriented process?

As you can see Casey's answer on his stream didn't really help clear things up for me so I was wondering if others could help me fully grasp these concepts and how they interconnect to generate an api.
Bill Strong
50 posts
Grapling with the ideas of writing the usage code first and compression oriented programming
You actually have the idea. Casey has said pretty much that in other answers. The hard part is learning to let your code be messy for a bit, until it actually wants to be compressed. Write the simplest thing that works. Then move on to the things that use it. But make sure your things that use it are working the way you want.

In the series, Casey changes the way drawing works several times, refactoring as he creates mores systems that use it. In some ways, the idea is not to make it perfect til the end. Get everything out of your head and where you can work with it.
Jason
235 posts
Grapling with the ideas of writing the usage code first and compression oriented programming
Okay. I guess the hardest part for me then to understand is if its best to write the simplest thing you can, then remove the duplication and generate the api, essentially letting the code guide where your api goes, then why would you ever need to write the usage code first to generate an api? It seems your api would already have been created by the bottom up approach of compression oriented programming.
Simon Anciaux
1337 posts
Grapling with the ideas of writing the usage code first and compression oriented programming
I think you're talking about two different things: api design and general "code design".

API on wikipedia
In computer programming, an application programming interface (API) is a set of subroutine definitions,protocols, and tools for building software. In general terms, it is a set of clearly defined methods of communication between various components.

So API means how you will call some system to do a task for you. I would simplify that idea to "top level function prototypes for a given system". While code design (e.g. compression oriented design) is more about how you design the internal of the system.

Write the usage code first refers to api design (see Designing and Evaluating Reusable Components - 2004 at 44:45). It helps you end up with an interface that correspond to what you want to use. Compression oriented design help you keep the code clean and easy to maintain. You write the simple thing first to know what you are dealing with and better understand the problem. Then you compress and see what the code becomes. At some point you'll need to make the API and the code fits together. You can change both sides. Writing the code probably raised some things you didn't expected with the API, and writing the API probably guided some of the choices you made while writing the code.

This video from Allen Webster (at 6:00) shows him reviewing some "usage code" before implementing it (I guess, I haven't watch the whole video) and maybe there is the part where he writes the usage code in a previous video.
Ben Visness
109 posts / 9 projects
HMN lead.
Grapling with the ideas of writing the usage code first and compression oriented programming
I find that writing usage code helps me see the big picture before I try to implement the details. It's easy to get lost in the weeds and forget why you were implementing something in the first place, and no good API is going to come out of that.

I have also found that compression sometimes helps me find a better API design, but it isn't always great for designing it in the first place. Usage code gives you a good roadmap to follow; compression helps you make your implementation better, and evolve your design.
Jason
235 posts
Grapling with the ideas of writing the usage code first and compression oriented programming
Okay, thanks for your insights. It seems like if you already have an idea of what a good, simple api might look like then write the usage code first and mock out your ideal design and then implement. But if your starting out by having no idea of what a good api would even look like, given a new problem domain, then it'd be best to start writing the simplest things that come to mind and compress. Eventually you'll start to understand more what a good api would look like and you can transition to writing the usage code first, alternating between the two as needed.
45 posts
Grapling with the ideas of writing the usage code first and compression oriented programming
You may be better off ignoring the idea of architecture altogether depending on where you are in terms of skill and experience. That's because a lot of API design has to do with tradeoffs which you won't really understand until having worked on larger projects for lengthy periods.
Bill Strong
50 posts
Grapling with the ideas of writing the usage code first and compression oriented programming
What you might find is that even as you get better at recognizing good api design, you start off at a better point in the process, but you can still get better design by assuming you won't get the best result the first try. If you think about the most complex system humans have ever built, society, you see it has moments of stagnation and the tendency to destroy itself if it stay the same way. Compression oriented programming keeps you in the mindset of never stagnating. You are always progressing.