or learn more


Nov 27, 2018

While listening to Starboy by The Weekend I’m reminded about some codebases that I have to dive into more deeply. When reading codebases, be they for fun or profit, I tend to take a systematic approach to exposing them, described as:

  • Get it building and running – not always as easy as it should/could be.
  • Change code to break it – Once it’s going I try to make changes to understand how and why they break things.
  • Understand all comments – Where applicable.
  • Delete all comments – To avoid biases.
  • Rename like mad – Going over the code I tend to rename functions and structures to fit my *current( understanding. This is an iterative approach as mu understanding deepens. In good codebases my final rename matches closely the original names.
  • Draw pictures – This is an ongoing and also iterative process.
  • Refactor code – Once I think I understand what it’s doing I try and refactor the code to my understanding. This hearkens back to breaking things. :p
  • (Re) Add comments – Comments are added back based on the understanding achieved (or not) and modifications made.
  • Read, read, read – Supplemental reading is an ongoing act.

Some great codebases I’ve read and mucked around with include:






  • Fennel – A Lisp compiler targeting the Lua runtime


  • Factor – The VM for Factor is pretty amazing



  • 10 PRINT – A book about a tiny fragment of Commodore 64 BASIC


Emacs Lisp

  • Advice – Function advice implementation

There are countless other interesting codebases to explore and over time I’ll point out some more. These should keep us busy for a while.


2 Comments, Comment or Ping

  1. M

    You have a typo, “Guave” should read “Guava”.

  2. Aaron Brooks

    That’s a great list.

    One thing that I find perennially useful is looking at the startup / initialization code. Getting all the pieces up and hooked together says a lot about how the broader system is expected to work.

    I’ve also found that understanding core data structures and tracing their lifecycles is very helpful. In the Clojure context, adding clojure.spec.alpha specs where these specs are missing adds helpful insights about your understandings of the domains of values in these data structures / shapes.

    I’d say that I typically execute the above activities shortly after getting things up and running and are part of the “break things” step.

Reply to “Starboy”