Code Layout: Thinking of code like any other document layout
I'm coding a lot these days - what did you expect from a software engineer trying to launch a startup? (Just kidding, we're not coding monkeys by any stretch of the imagination). In my bouts of code I often find myself frustrated with the experience. While fingers can be pointed to a temperament concern (it's reasonable - I have a low tolerance for low quality products + experiences), this is simply a misdirection away from the problem. Coding feels so slow and really it feels like it should be much faster.
Along the lines of what I want to write about, this is probably is going to be a huge theme: make building high-quality software faster.
Today I've been faced with code structure for example. I'm writing a microservice in python and I'm finding myself having to rewrite things I've written before. Things like how to structure my main application entrypoint, port management (if deploying multiple services on a single machine for example), host vs. path vs. header based routing, etc. In technology, there are what feels like infinite layers of abstractions and decision points to make, and these decision points are often obfuscated by technology implementations (instead of transactional vs columnar DB, it's often do I use RDS postgres or some other SQL).
I'm always learning, but the thing with human beings is, even if you're an expert, you forget things. If you have millions of abstraction layers to learn about - you'll never get anywhere or you'll move way too slow. What I've seen in my experience thus far is that these choices at the low level don't matter to really "redo" every time you want to do something - you're usually just looking for the product or feature to get shipped and be high quality - everything is is just an implementation detail. What matters are the constraints that define high quality. This is where we get to system design-like concerns - CAP, security, reliability, durability, scalability, etc. However, in trying to satisfy these concerns, you're chasing weeds in the millions of abstraction layers. We can do better - and we have to do better. The time gap between having an idea and creating something based off of it is too high - and it creates an artificial barrier of entry to those that aren't capable of being versed in the millions of abstraction layers. It creates gatekeeper-esque software experts who in their pedanticism - much like W3C prior to WHATWG forcing their hand with HTTP5 et al - create walled gardens.
it shouldn't take an expert to build an entire high-quality app in days. Expertise of software engineering hasn't found a way to sufficiently scale beyond cloud computing. Ask your college student in a CS program if they can navigate a behemoth like AWS.
It feels like there is a gap that doesn't reduce creating new apps go from months to weeks and weeks to days and days to hours. Often, to get an MVP out, it feels like you're looking at a few weeks minimum to get an extremely skinned version of the product you're building. If this skinned version is 5% of what the product should do, then I feel we can get an 80% version of what the product should do in the same timeframe by scaling software engineering expertise. How exactly? Well, that's for another day - I don't have a silver bullet exactly. It's a task of taking a bunch of bricks and finding the way to stack them that works.
Like many, when you're bouncing around shipping one thing or the other, the context switch makes your memory very fallible.
Anyways, for code structure, you have a concept of scope in programming languages - in a nutshell, it defines what variables are avaiable at a particular line. In a written document, let's say a blog post, you break down by scope as well. How? You use concepts like:
Title, sub-title, indented unordered/ordered lists, quote blocks, headings, sub-headings, and the like. Each of these concepts, surprisingly, don't always have an obvious in coding.
Take for example:
```
def foo(a, b):
# do some stuff with a
... 10-15 lines of code
# do some stuff with b
... 10-15 lines of code
# do something logical that's not really specific to a or b
... 10-15 lines of code
```
In a document, you have a few different ways you might structure that - but ultimately, you're thinking about how to structure the document. A massive wall of text and a massive wall of code are the same - they suck to read through. Imagine on page 80 of an essay, it uses a term that was defined on page 23. Even if there is a link back, you're going to lose your mind if you have to do this every minute.
Instead, you use sections to scope the content. Our code could change to using functions to represent sections:
```
TODO example
```
But there's some issues with this approach: functions impact execution not just visuals. We could also use comments instead:
```
TODO example
```
But there are issues with this approach as well. Comments are hard to enforce standards around. Standalone comments are totally valid - how can you discern between a series of valid comments and a series of sections with subcomments? It's an interesting quandary.
Of course, this will vary per language as well.
Of course, code organization doesn't have a solution, it's more of a barometer of "easy to manage / easy to read vs. hard to manage / hard to hard to read"
A side plug: I used chatgpt today, and I'm leaning on it more and more to help it answer questions that I know would be hard to craft into a good search query. For example, I forgot what the term NAT, but only remembered the concept. I've had to become really good at networking at some point and things like NAT, subnets, route tables (iptables), etc. were front of mind. But that's a brief episode in what is a multi-season series that is your experience as a software engineer at a startup that goes from Series B->IPO. A good quote from one my mentors who founded Compass went roughly like "the luxury of remembering what you worked on is afforded to those that don't move fast enough".
Anyways, that's today's word vomit.
