Refactoring from one large main go file

3 minute read Published:

How to move from a house of cards to a villa of cards

How to move from a house of cards to a villa of cards

Disclaimer: I am absolutely a Go beginner. In fact it’s the first typed language I’ve worked with. I am used to PHP and JS and Ruby which feels like the bohemian side of the beach compared to Go, but that’s not always a good thing. On this more elegant side there is an air of purpose with beach umbrellas conveniently already on the sand for you to use. Sometimes they’re Ikea umbrellas and you have to do some building yourself but at least there’s good documentation.


I recently had a project for work where I had to make a scraper for websites in order to parse and port articles over to a new system. Since I’m new to Go I shoved everything into a main package and quickly realized that I am overwhelmed with the amount of scrolling I have to do. The standards for documentation in Go is extremely helpful but still not enough. My code wasn’t too big to fail. It was too big to succeed. This is the thinking process I went through to find a sort of modularity.

Some things to keep in mind:

  1. Packages can be spread across files (useful if you only want to organize the code)
  2. The javaScript world seems to be all about modularity these days but please take caution. Too much modularity can be just as confusing as one giant file.

Let’s get going!

  1. Start a new document and use it for organizational brainstorms
  2. Take a good look at all your functions and structs. Either list all functions (with inputs and outputs) with a line or two about what it does, or use code folding so you only see the top level of what’s going on. Please feel free to use this step to create descriptive documentation about your code. This step forces better documentation and a better understanding of your functions.
  3. If you notice certain functions are getting out of scope and are too big for their own good maybe now is a time to refactor that function into smaller functions (think single responsibility principle).
  4. Start lumping functionality together
    • Example:
      • If words keep popping up like “Article” consider putting them together
      • Maybe make a utility package for misc functions that are more like utility / helper functions.
  5. Consider breaking things out into their own packages and importing them at the top of your go files.
    • I ended up doing this for a class of functions that only dealt with the database layer. This made it so much easier to abstract a lot of the database logic away from the bulk of the code which made everything else more readable and simpler to think about. Another benefit I received is that when I wrote new small go packages for slightly different purposes I was able to bring this database layer in to jump start my productivity.
  6. Make sure you’re version controlled (checkout a new branch) and break things apart. Start small. Maybe just move a few things into a new file and then keep coding. Don’t get overwhelmed in abstraction and trying to future proof your code.
    • You will save yourself so much trouble by only taking small steps. If you’re starting a small restaurant, one cook is too little but ten may be way too many. (replace cook with code-base, file, and files respectively).
  7. Pat yourself on the back, go drink a beer and be proud. You just made your life easier.
comments powered by Disqus