Best Practices for Writing Clean and Maintainable Go Code

"Any fool can write code that a computer can understand. Good programmers write code that humans can understand."

- Martin Fowler ^[8]

Writing clean code that is easy to test and maintain is much harder than it seems at first glance. Fortunately, Go, as a programming language, is quite opinionated and comes with its own set of best practices.

If you take a look at some of the available material for learning Go (for example, Effective Go ^[6]) or watch some talks by prominent members of the core Go team such as Rob Pike, it becomes evident that software engineers are gently nudged toward applying those principles when working on their own Go projects. From my perspective and experience, these best practices tend to have a measurable positive effect on the code quality metrics associated with a code base and at the...

The SOLID principles of object-oriented design

The SOLID principles are essentially a set of rules for helping you write clean and maintainable object-oriented code. Let's go over what the initials stand for:

• Single responsibility
• Open/closed
• Liskov substitution
• Interface segregation
• Dependency inversion

But hold on a minute! Is Go an object-oriented language or is it a functional programming language with some syntactic sugar tacked on top?

Contrary to other, traditional object-oriented programming languages, such as C++ or Java, Go has no built-in support for classes. However, it does support the concepts of interfaces and structs. Structs allow you to define objects as a collection of fields and associated methods. Even though objects and interfaces can be composed together, there is, by design, no support for classic object-oriented inheritance.

With these observations...

Organizing code into packages

As we saw in the previous section, the application of the SOLID principles works as a guide for splitting our code base into smaller packages where each package implements a specific bit of functionality and its interfaces serve as the glue for wiring packages together when building larger systems.

In this section, we will be examining the idiomatic Go way for naming packages, as well as some common potential pitfalls you may encounter while authoring code that relies on a complex package dependency graph.

Naming conventions for Go packages

Let's say you come across a package named server. Is that a good name, as per the preceding suggestion? Well, obviously, we can guess that it's...

Tips and tools for writing lean and easy-to-maintain Go code

In the upcoming sections, we will be covering some techniques, tools, and best practices that can assist you in writing more concise and clean code that is easier to test and at the same time help you get some praise from your colleagues and code reviewers.

Most of the topics that we will be discussing are specific to Go, but some of the principles can be generalized and applied to other programming languages and software engineering in general.

Optimizing function implementations for readability

During my early university days, my CS professors would be adamant about keeping function blocks short and concise. Their advice went along the lines of the following:

...

Summary

In the first section of this chapter, The SOLID principles of object-oriented design, we performed a deep dive into each of the SOLID principles and how they can be applied toward writing clean Go code:

• SRP: Group structs and functions based on their purpose and organize them into packages with clear logical boundaries.
• Open/Closed principle: Use composition and embedding of simple types to construct more complex types that still retain the same implicit interface as the types they consist of.
• LSP: Avoid unnecessary coupling by using interfaces rather than concrete types to define the contract between packages.
• ISP: Make sure your function or method signatures only depend on the behaviors they need and nothing more; use the smallest possible interface to describe function/method arguments and avoid coupling to the implementation details of concrete types.
• DIP: Use the...

Questions

1. What do the SOLID acronym initials stand for?
2. Why does the following piece of code violate the SRP? How would you refactor it to make sure it doesn't violate it?

import (
    "crypto/ecdsa"
)

type Document struct { //... }

// Append adds a line to the end of the document.
func (d *Document) Append(line string) { //...  }

// Content returns the document contents as a string.
func (d *Document) Content() string { //... }

// Sign calculates a hash for the document contents, signs it with the
// provided private key and returns back the result.
func (d *Document) Sign(pk *ecdsa.PrivateKey) (string, error) { //... }

3. What is the main concept behind the ISP? Discuss how would you apply it to improve the following function signature:

// write a set of lines to a file. 
func write(lines []string, f *os.File) error {
    //...
}

4. Explain why util is considered...

Further reading

1. aligncheck: Identify inefficiently packed structs. URL: https://gitlab.com/opennota/check.
2. bodyclose: A static analysis tool that checks whether res.Body is correctly closed. URL: https://github.com/timakin/bodyclose.
3. copyfighter: Statically analyze Go code and report functions while passing large structs by value. URL: https://github.com/jmhodges/copyfighter.
4. deadcode: Report unused blocks of code. URL: https://github.com/tsenart/deadcode.
5. dupl: Report potentially duplicated blocks of code. URL: https://github.com/mibk/dupl.
6. Effective Go: Tips for writing clear, idiomatic Go code.
7. errcheck: Ensure that returned errors are checked. URL: https://github.com/kisielk/errcheck.
8. Fowler, Martin: Refactoring: Improving the Design of Existing Code. Boston, MA, USA: Addison-Wesley, 1999 — ISBN 0-201-48567-2 (https://www.worldcat.org/title/refactoring-improving-the...