Creating Go modules is more than writing code

Go modules provide a powerful way to package and share your code. However, creating effective modules requires comprehensive software engineering practices that go beyond simply writing code. There are crucial steps that shape the design, evolution, and maintenance of your modules. Let's explore what they are in this short post.

Scope boundaries

As you develop your new module, you should set boundaries about the scope of the problem it is solving. If your module provides multiple functionalities, capture those functionalities into well-defined packages within the module.

Properly name all the things

Naming can be hard when building software. However, you can make it less painful when creating Go modules by adopting practices that focuses on import aesthetics.

• Select a meaningful repository name for your module as this will impact the import path of all of your packages
• Package names should short and concise while indicating their respective functyonalatities
• Avoid deep package directory nesting (no more than 4, please for the love of all that is good)

Testing is essential

Go is one of the early languages that intrinsically support testing. As you develop your module, provide robust test suites (at least close to it) for the functionalities exposed in your packages. This ensures that your module libraries work as intended and can help to catch bugs early.

Document your module

Sometimes documentation is neglected or completely avoided. However, this is the one way you can communicate with the human who will be using or maintaining that code (including yourself). Fortunately, there are many places to capture documentations when developing Go modules.

• Provide light description of the code, especially exported code elements
• Provide context about your packages using package-level documentation
• Provide some descriptive and usage documentation of the module itself using a README file. If you feel adventurous, you may include a docs directory with additional content for your module.
• If you plan on doing regular versioned releases, document your changes so users know what has changed.

Version your code

Go modules require the use of semantic versioning as a way to indicate to users the current health of the module. Use the semantic version numbers to let users know when your release include bug fixes, new features, or breaks in backward compatibility.

Conclusion

Creating Go modules is more than throwing together some packages. By carefully considering the broader implications of problem-solving, design, documentation, and maintenance, you'll create modules that will not only be valuable to others but will stand the test of time.

Learn more

You can learn more about the steps covered in this post and how to effectively develop Go modules in the LinkedIn course Programming with Go Modules.