Best Practices for Commenting Code

Oct 29, 2020 by Lane Wagner

I often hear that we need more and better comments in the code we write. In my experience, we frequently need better comments, we rarely need more, and we sometimes need less. Before you crucify me for my sacrilege, let me explain by giving you some of the “rules of thumb” I use for deciding when I should add a comment to my code. First, do no harm. If a comment is incorrect or outdated, update it or remove it Incorrect documentation is worse than no documentation.

The Nuances of Constants in Go; Go Isn’t JavaScript

Oct 22, 2020 by Lane Wagner

Constants can be confusing and easy to misuse in Go if you are coming from an untyped language. Let’s take a look at some of the nuanced details of how they work in Go. It’s probably unsurprising, but Go’s constants are almost nothing like JavaScript’s bastardized version of the concept. Go vs JavaScript Many programming languages support constants, often denoted by the keyword const. Go and JavaScript both declare new constants in the same way:

Practical Patterns for Technical Writing

Sep 22, 2020 by Ben Barten

Writing technical documents like API or architectural documentation which exceeds a simple flow diagram can be a daunting task. If you have some experience with technical documents, you will probably agree that there is nothing more frustrating than bad documentation. Lately, technical writing has become a more important part of my job, so I put together some of my findings. I use the following checklist and hopefully, it can help you as well.

How to Make Pure Functions in Golang

Sep 07, 2020 by Lane Wagner

Pure functions are often hyped up in the JavaScript world, probably because of the abundance of stateful front end applications. While pure functions have their downsides (i.e. inconvenience, potentially large argument lists), they should be used as much as reasonably possible. What is a Pure Function? According to Wikipedia, a Pure function has the following properties: Its return value is the always same for the same arguments Its evaluation has no side effects (no mutation of data outside the function) Which means that as a developer I know two important things:

Guard Clauses - How to Clean up Conditionals

Sep 06, 2020 by Lane Wagner

One of the first concepts new developers learn is the if/else statement. If/else statements are the most common way to execute conditional logic. However, complex and nested if/else statements can quickly become a cognitive burden and compromise the readability of a program. Guard Clauses Guard Clauses leverage the ability to return early from a function (or continue through a loop) to make nested conditionals one-dimensional. Instead of using if/else chains, we just return early from the function at the end of each conditional block.

Should You Return Empty or Nil Slices in Go?

Sep 03, 2020 by Lane Wagner

In Go, we often need to return zero values. Idiomatic Go encourages the use of guard clauses, and guard clauses necessitate the need to return early. When returning early with an error, by convention all other return values should be zero values. The confusion arises with data types like maps and slices. Should maps and slices be returned as a simple nil value, or should an empty but instantiated value be returned?

Slow Is Smooth, Smooth Is Fast - 25% of Our Time Refactoring

Sep 01, 2020 by Lane Wagner

My team has been spending less of our “free” time working on bugs and features from the backlog, and more time refactoring our code and tests. As a result, and perhaps somewhat counterintuitively, we’ve noticed a significant increase in our throughput of features and bug fixes. As it turns out, it’s easy to find bugs and add features to a well-written codebase that the entire team is familiar with. Go figure.

Make Maps and Slices in Golang - A Guide to Initialization

Jun 29, 2020 by Lane Wagner

There are quite a few ways to create new maps and slices in Go, for example, they can both be initialized using the make() function, the new() function, as literals, or by using the var keyword. With so many choices, which option is best? Or perhaps better asked, which one is best in your situation? Let’s take a look. Slices var varStyle []string literalStyle := []string{} newStyle := new([]string) makeStyle := make([]string, 0) var varStyle []string is the idiomatic way to declare an empty slice.

How to Get Consistent Line Breaks in VS Code (LF vs CRLF)

Jun 18, 2020 by Lane Wagner

Have you ever had the problem where you submit a pull request and the diff is much larger than it should be? Maybe the code looks identical, but GitHub tells you it’s completely different? This is typically due to a difference in line endings, especially the difference in LF vs. CRLF. Unix systems like Linux and macOS use LF, the line feed character, for line breaks by default. Windows, on the other hand, is special and uses CR/LF, carriage return AND line feed character, by default.

Sorting in Go - Don’t Reinvent This Wheel

May 27, 2020 by Lane Wagner

Sorting is a common task in programming, and for that reason, most languages have a default sorting algorithm in their standard library. Go is one such language. Go has gone about providing sorting functionality in one of the most elegant ways possible, via an interface. type Interface interface { // Len is the number of elements in the collection. Len() int // Less reports whether the element with // index i should sort before the element with index j.