An Efficient Go Study Guide

I'm currently learning Go by working on a Twitch support website and had to go through their documentation. As many of you may know, I have a thing for documentation and Go's is...weird. On the surface it seems like it has everything you need, but when you actually try to use it the organization and writing style is all over the place. This blog post is an attempt to help anyone else trying to wade through this weird set of documentation by reorganizing it into a more logical progression of topics.

The List

This is a reorganization of Go's Official Documentation into a structure that I think is more logical. It's difficult to do this since I don't actually have control over their docs so I can't rewrite or add any that would fill in gaps. For example, you'll see there's not a lot on error handling but tons and tons of documents covering modules. You'll have to take this as a rough guide that will get you an 80% solution to the problem, rather than the current 20% solution on the official site.

I believe the difference between my list here and Google's official layout is one of when to teach something important. Programmers frequently think that if something is important, it should be taught first. The problem is, important topics in computer science are complex amalgamations of other simpler topics, so placing them first places a massive burden on people to already know everything. What I tried to do was save the important topics for later, building up to them in tiny increments so people know what they need to understand the important things. If it's important, you should take your time.

If you think something is missing and have a good link, shoot me an email at help@learncodethehardway.com with a link and where you think it fits. If I agree I'll include it at the right spot. Just remember that you have to invert your tendency to want to teach "important things first" as I mention above.

Installing Go

Obviously you'll need to start here if you want to learn Go. I'm using Go on both Windows and OSX and I'm finding it's extremely portable and easy to use on both. I'd give Linux a slight edge though in simplicity. Also, you can install Go easily with winget and it's the latest version. On Debian I had to install manually since the version is very far behind. On Windows use winget install GoLang.Go.

A Tour of Go: Welcome

This is fairly short and mostly repeats a bit of the Installing Go document. Worth going through just to confirm the Tour works for you and you're all setup correctly.

Tutorial: Getting Started

This is kind of a weird getting started document because it makes it seem like the only way to use Go is with a monorepo style subdirectory. You don't have to do it that way, and whenever you see this kind of document (which there's many of) you can usually ignore the monorepo thing they're pushing. I get the feeling Google has a big problem with code organization so they get the Go project to frequently over document how to use modules/packages.

How to Write Go Code

I consider this to be the real "Getting Started" document. It explains nearly everything you need to get started, from how to structure your code, to your first little "Hello, World." program, to installing your own package to use. NOTE: The flaw of this document is it makes it seem like you have to do all this package install stuff to just use your code. You don't, but it's nice to learn.

A Tour of Go: Basics

Now that you have a good first start going you can learn some initial syntax, more on modules/packages (because apparently that's the most important topic in the whole universe) and then functions and how they work. There's also good information on using fmt.Printf, variables, and types.

A Tour of Go: Flow Control

You can then learn about Go's flow control constructs such as if, switch, and for. Go has made the interesting choice of only having for as the loop construct, but it's flexible enough that you're not stuck with it. It will work as a traditional while, a C style for, and a Python style for-each.

PROJECT TIME At this point I recommend using what you know to implement a "Text Adventure Game" similar to Colossal Cave Adventure. These are very fun to make and don't require anything more advanced than what you already know.

A Tour of Go: More Types

You are now ready to learn about pointers, structs, and data structures such as arrays, slices, and maps. Go's approach to these is fairly simple, but works well enough.

PROJECT TIME A good way to learn Go's (or any language's) data structures is to implement either a CSV parser, or a log file parser. Take some time to write either of those and use them to calculate some basic statistics.

Go Specification: Types

I'll frequently point you at relevant parts of the Go Specification but I don't think you should dive too deep into it. My suggestion is to read through it, type up the code where you're interested, and then make mental note that it's there. In this section it covers the types you've learned so far in more detail according to the specification.

A Tour of Go: Methods

Back to the Tour you now start to learn how Methods work, which is Go's simplified version of OOP...sort of. I'd say it's probably better than traditional OOP since it gives you a lot of the benefits of a class/object system, but none of the footguns like inheritance. One thing to watch out for is that a lot of Go code is kind of random as to when something is a Method and when it's a function in a package. Also, the documentation generation tool doesn't properly document when a Method applies to multiple structs.

Go Specification: Built-in Functions

Another part of the specification that explains many common built-in functions you may need to know. As I mentioned before, read it briefly then refer back to it as you need.

Go Specification: Packages

Again, just read through this for your information, but not useful to memorize.

Writing Go Web Applications

There's a strange document that tries to teach creating an API with Gin, but the community seems to consider anything outside of the standard library a forbidden black magic. Not sure why Gin gets a pass but the Go Discord FAQ rants about Fiber, but I guess that's Open Source for you. Either way, I'd skip the Gin document as it's not very good and just go through this one.

Go net/http Api Docs

I imagine you're like me and planning on using Go for web development, so you should probably spend a lot of time here. I'd go through all the functions, make notes on them, and recreate all of the examples. Doing this will significantly up your Go skills. WARNING: The Go documentation tool hides examples from you so look for the little Example> expando thing and click on it. Usually there's one under most functions.

PROJECT TIME Use what you know to create a small blog or other website. Go's killer feature is its ability to create network services insanely fast that are fairly competent for the time you spend creating them. You should also check out the existing protocols in net.

Accessing a Database

You don't need to install MySQL like in this document. You can just use go-sqlite3 and learn it that way. I actually have no idea why Go doesn't have a built-in sqlite3 driver like every other language on the planet given that sqlite3 is the most deployed database on the planet.

PROJECT TIME Now that you know databases add a comment system to your blog (or whatever you made). Extra points if you can make a Forum system.

Getting Started with Generics

Generics are fairly useful but Go's done a decent job of not needing them for most of its existence. Be warned that a lot of the documentation about them is fairly thin, so just learn about it and look for places to use it.

A Tour of Go: Generics

Way too thin for this topic but it's a bit more information about generics that can help you understand them. A good way to think of Generics is as a "code generation template" similar to an "HTML generation template".

A Tour of Go: Concurrency

A decent overview of Go's concurrency model, which is a really good system compared to other languages. I believe it's not the fastest, but it is really easy to use and doesn't have nearly as many footguns as threads.

Go Specification: Defer Statements and Handling Panics

Decent enough docs on this kind of weird error handling system, but honestly this is rarely used. I almost feel like they just added this strange recover() mechanism in protest to spite the people who complain about Go's error handling. It's just so weird, and would have been better done with a simple recover keyword that acts as clean-up jump.

Go By Example

Finally, you should go through the examples here and confirm you know everything in them. If you don't then circle back and look through the previous documents and the Go Specification to re-learn what you missed.

Struct Tags

Easily the best damn feature in Go, and something I think every language should pick up. Tags effectively allow you to annotate a struct with information that is used to integrate with the outside world. For example, you can give different names to fields so they match a Data Base, a remote JSON protocol, or add Validation rules.

Well Known Struct Tags

A list of well known tags you can use and how to use them. There's so many.

PROJECT TIME: Use your knowledge of tags and the go-playground/validator library to add automatic form validation to your web application. You can also use the tags to create JSON APIs for your web project.

Project Time

You should now try to make as many tiny Go programs as you can. You'll get way more educational value out of 100 tiny projects than you would from a single gigantic project. If you're struggling for ideas just copy any command line tool, website, or game. Just keep copying until you find your own voice and ideas.

Nothing's original anyway, and even if someone did it before, you didn't and that's all that matters.

Additional Topics

flags

For command line options. Pretty nice actually.

strconv

Seems to be missed in much of the documentation but comes up often enough.

Ebitengine

Really good game development library for 2D games.

PureGo

Go FFI interface that uses embedded ASM to do the calls rather than CGo.

Missing Documents

• You'll notice I don't have every module document because there's far too many while none of them being complete enough for people to know how to organize their projects. It seems to me like the Go project knows their modules are vomit from Google Monorepo but are loathe to mention this, thus the seeming dancing around the topic endlessly.
• I couldn't find any very succinct error handling documentation, which is weird given there's 200 documents on modules/packages. Again I think this is on purpose since the Go project knows that its error handling is plain weird so they don't want to get into it. A series of lessons in Tour of Go that solidly laid out how to handle errors would vastly help people.
• For some reason there's people who think the weird defer()/recover() error handling is how people are expected to handle all errors, even those that are normally done with the usual if err != nil. Thus one more reason why there needs to be official docs on how best to handle errors so people don't think the fallacy of "newer == officially better."
• No documentation on how to actually use reflect other than this weird blog post that's trying to be a parody of The Laws of Attraction named The Laws of Reflection. Numerous people I've talked to have said that Go's blog posts are "really weird."

Something Missing? Mistakes?

If you think something is missing, or that I should add more to this please email me at help@learncodethehardway.com. I'd also appreciate any corrections, but please include references so I can go research.

More from Learn Code the Hard Way