How to write g̶o̶o̶d no, great code
A non-scientific, completely subjective opinion from some random dev online.
🙄 who’s this guy think is is? What does he know about writing “great” code?!
You’d be 100% right for thinking that — and to be completely honest… I have much much more experience writing not great code.
not great code gets written for many reasons (some listed below)
- its hard
- “great” is subjective
- software is never done (can’t “be” great, has to “stay” great)
- quality can change based on current requirements
- lots of functioning software isn’t great (bad role models)
- people who want software are often not software engineers
- …
However, occasionally… in rare circumstances… either by extreme effort or pure luck, great code is born.
Despite my deep experience with suboptimal code — I have nearly a decade of experience asking computer (as kindly as possible) to do the things that I and other humans want.
Over this time I’ve come to appreciate various concepts and patterns, and also learning a deep mistrust for others.
In this article I’ll outline some of the good and bad’s of software — and provide supporting evidence from actual smart people.
Welcome to the ride
What is “great”
Lets start by defining what “great” is. However it might be easier to define by quickly stating what it is not.
Great code is
- not hard to read
- not hard to reason about
- doesn’t cause you to hate yourself today or 7 days after writing it
Great code is
- 90% structure and 10% syntax
- a function of information abstraction paired with predicted resource management
- a friend of math (specifically set/category theory)
- written for humans not hardware
Can you elaborate
1. 90% structure and 10% syntax
All of theses ideas are inspired by much more comprehensive and deeper topics. Regarding structure we can look to the SOLID programming paradigm.
SOLID stands for a set of 5 “rules” that should be followed to build maintainable software. Concepts listed below
S - Single-responsiblity Principle
O - Open-closed Principle
L - Liskov Substitution Principle
I - Interface Segregation Principle
D - Dependency Inversion PrincipleThese principles were create by Robert C. Martin (aka Uncle Bob), and I cannot recommend diving headfirst into these concepts enough!
These principles revolve around the power of Object Oriented Programming (love it or hate it) and describes an elegant way to slice your abstractions into software friendly chunks.
By following these principles you can avoid many nasty complexities that arise in functional software.
For example, with SOLID principles you’ll reduce the footprint of your code and center files around common functionality; making it easier to navigate and add/remove features without affecting other parts of your codebase.
These issues are wholly avoided at the structure level of your application — rather than at the code level 💃
Structure level cleanliness is a powerful way to enforce lasting organization.
Easy to digest article on SOLID by Digital Ocean: here
If that wasn’t enough — Uncle Bob has continues to drop bangers 🔥.
I would highly recommend his more recent book released in 2017 (and honestly everything more recent too).
“Clean Architecture: A Craftsman’s Guide to Software Structure and Design” — https://www.oreilly.com/library/view/clean-architecture-a/9780134494272/
This book explores how you can extend these concepts to the system level.
As we move more applications into “the cloud” and leverage distributed services. These design principle have more and more impact on the greatness of your code.
great code is just a tool that fills the structure of your applications design, your system should be expressed via it’s structure not syntax.
2. a function of information abstraction paired with predicted resource management
um… what. You really lost me with that one. a function of whaa?
lets break it down.
“a function of information abstraction” is a concise way to express that our code is the output of our abstractions.
In other words — our code is a reflection of how we decided to slice up the concepts of our application.
More concretely; if we are faced with a problem and decide that we should create “Users” and “Sessions”, we’ve effectively sliced our problem into those abstract ideas of users and sessions.
…okay 👌 I think we got the “a function of information abstraction” covered.
Next we pair that with “predicted resource management” which is a fancy way to say that software engineers are tasked with being able to see into the future — and build systems that can withstand future changes 🔮
If you didn’t know — its your fault as the programmer that you didn’t use the newest framework a year before it was created. How’d you not know!? (please read as sarcasm — I promise this isn’t personal).
So, to summarize; the quality of our code isn’t always it’s computational complexity, number of lines, or elegant variable names.
It’s the ability to effectively slice your problem into abstract chunks that will withstand the unforeseeable changes of tomorrow.
Yes yes yes, I know; that doesn’t seem possible. Well it isn’t — and its our job as developer to manage the things we know, and the things we know we don’t know.
Its an exercise in risk assessment and cost planning — huh, didn’t know you signed up for that did you.
However, there’s hope!
By following trustworthy concepts (more to come shortly) we can harden ourselves and applications for a changing world.
Before we get into the really good stuff — we can acknowledge some “trust” worthy ideas here.
- Standards bodies (theres people who’ve thought deeply about it already — and they’d really appreciate if you make use of their great work. This especially applies to algorithms, security, cross platform and other really important things like QR codes).
- Static and Strongly typed languages (honestly this isn’t really about the low level security issues you’ll avoid. It’s about the human centric nature of types. one, if you violate the type in your code the compiler will yell at you, and two, other devs will actually know what your code is doing).
- Poetry (less about the words and more about the ability to communicate complex meaning with few symbols. Your code is poetry, albeit a very unimaginative audience but still it should read short and sweet).
3. a friend of math
While you might not be — your code should be buddy buddy with math.
Yes, I know — math is boring and you’ve never used a derivative in real life.
But…. I promise — it can be super helpful. Its actually the most trustworthy tool we have.
It’s trustworthy because it has a long history of open source contributes and they’ve worked out most of the bugs in the core software. Now the devs (mathematicians) are busy figuring out crazy things like quantum physics.
We can trust the useful stuff like cryptographic to secure our bank accounts and communications. We can trust set theory to enforce [ADD FAVORITE PROGRAMMING LANGUAGE HERE]’s type system. We can even go as far to trust linear algebra to optimize our route on Google maps and ChatGPT to stay silly things.
It’s important to remember that behind all of the fancy UI and shiny screen — our computers are just that; compute-ers.
If you strip away all of the complexities you are left with the barebones of addition and subtraction.
Maybe, just maybe… theres a way we can bubble all of that power up to our own code.
Let dive a bit deeper 🤿
I’ll take a wild guess and assume that you (the reader) is familiar with Object Oriented Programming,
And… I’ll also go as far to guess that you’ve heard of Functional Programming — but decided that was something to learn about another day.
If you are in that camp, then you may not be aware of the beauty and elegance of programming languages that more closely follow semantics of traditional math.
We (normal people) are spoiled with the abstractions the mainstream languages provide. We expect to be able to create variables whenever we want, and construct complex control flows with a towers of if and else
We (normal people) should however, take note from our smarter functional programming counter part.
There are hidden superpowers in simple and constraining languages. They provide provable (⚡️ powered by math) methods to show that your code covers all cases, or that it can be broken into discrete pieces of work that can be spread across infinite machines.
Infinity and Proofs are difficult ideas for the average programmer but any mathematician eats them for breakfast.
For example one of these superhero in the video below, shows how modeling a system can provide ways to find step by step instruction to exploit incredible complex bugs without looking at a line actual code 🤯
The secret lies in the power of formal math applied to system design.
If applied correctly (and no this does not require rewriting everything in a functional language), then you get all of the benefits of math for free.
These benefits include but are not limit to
- automatically generating test for every single possible way your program could be used
- explore the implications of adding removing components or systems to your application
- be 100% sure that code will work. You wanna be really sure that your airplane landing gear software works don’t you.
- other more complex things that the speakers in these video can teach you about. Oh and if you’re really serious about learning this check out TLA+
In conclusion — maybe math isn’t bad after all.
Maybe we can use some of those amazingly boring concpets to make our code boringly amazing.
great code should aspire to have such concrete ideas that those same ideas hold true more than 1000 years from now
Pathagotem came up with some great software for triangles in ~570 BC…. thats like 1500 years ago!
Maybe we should learn from, or use math when possible — its the best way us humans know how to express long lasting abstractions.
4. written for humans not hardware
Okay enough on the math stuff. When we talk about software — as much as we try to avoid humans. They always come into the mix.
Lets talk about humans. How do humans fit in?
Well… they’re the ones who want the software in the first place, and actually they’re the ones who came up with these languages.
Furthermore they’re the ones who care about this whole thing — computers dont’ have opinions on the code they run.
People do. People define what is “working” and what isn’t.
So — I guess we should orient everything for the human right?
Yes! and that doesn’t just mean that we need pretty UI’s and ergonomic mobile apps.
We need to extend the humanity into the software development. We should feel this at many levels.
Humanity should be in the developer experience at all levels. The following are some human centric questions.
- People are onboarded to codebases. Does your documentation facilitate that?
- How many tools/commands or special setup steps do I need to take?
- What does it look like adding a new test? a new feature?
- How many frameworks/languages does your project impose? Could it be less?
- How much effort is to to go from completely new to fully in production?
- What does breaking look like? and will I need to wake up to fix it?
Outside of those questions — we need to think of the group dynamics. One good developer is kinda powerful.
But a small team of good devs is greater than the sum if it’s parts (when done correctly).
So how do we get great code out of a team?
Some solutions are easier than others. For example an easy but effective one is to standardize everything — remove all personality from indvidual contributions.
While that sounds harsh — a solid systems will have specific ways/types/patterns to do things. There should be very little customization and creativity inside the syntax of the code.
Why is this a good thing? It greatly eases the mental load on the developer. If theres a “way” to do something — then it should be done that “way”.
This effectively moves the solution from the code level into the structure level (mentioned ealier). Since we need to rely on system level decisions and patterns rather than bespoke ones.
More simply put, all devs should share common types. This removes customization and makes it much easier to integrate various devs work.
This idea should extend way further than types and as many concepts that can be effectively standardized at the system level the greater your code will be.
great code is so well written contributions from different team members is is often indistinguishable from other parts of the codebase. Additionally you shouldn't be able to see where one person started and another finished.
In the following video, strategies for building teams and increasing productivity as a system becomes more complex are explored in detail.
This is a fascinating topic since the ideas of complex system design are well outside of the scope of computers and touch upon natural phenomena like animal/plant biology, social interactions and planets.
Us mere mortal/developers hold a lot of power in our hands. We can construct massive piles of complex and useless s*** — and with those same hands can build our own complex dynamic systems not to different from the planet I’m writing this on.
Till next time, keep coding, spread love and peace out ✌️
