The wonderful thing with Go when it comes to best practices is that even if you don't necessarily do everything right, either Go will yell at you or provide you with the tools necessary to fix it.
If you attempt to include code and not use it, or if you attempt to initialize a variable and not use it, Go will stop you. If you want to clean up your code's formatting, Go enables it with go fmt
.
One of the easiest things you can do when building a package from scratch is to structure your code directories in an idiomatic way. The standard for a new package would look something like the following code:
/projects/ thisproject/ bin/ pkg/ src/ package/ mypackage.go
Setting up your Go code like this is not just helpful for your own organization, but allows you to distribute your package more easily.
For anyone who has worked in a corporate or collaborative coding environment, documentation is sacrosanct. As you may recall earlier, using the godoc
command allows you to quickly get information about a package at the command line or via an ad hoc localhost server. The following are the two basic ways you may use godoc
:
Using godoc |
Description |
---|---|
|
This brings |
|
This hosts the documentation on port |
Go makes it super easy to document your code, and you absolutely should. By simply adding single-line comments above each identifier (package, type, or function), you'll append that to the contextual documentation, as shown in the following code:
// A demo documentation package package documentation // The documentation struct object // Chapter int represents a document's chapter // Content represents the text of the documentation type Documentation struct { Chapter int Content string } // Display() outputs the content of any given Document by chapter func (d Documentation) Display() { }
When installed, this will allow anyone to run the godoc
documentation on your package and get as much detailed information as you're willing to supply.
You'll often see more robust examples of this in the Go core code itself, and it's worth reviewing that to compare your style of documentation to Google's and the Go community's.
Assuming you've kept your code in a manner consistent with the organizational techniques as listed previously, making your code available via code repositories and hosts should be a cinch.
Using GitHub as the standard, here's how we might design our third-party application:
Assuming your repository is public, anyone should be able to get (go get
) and then install (go install
) your package.
One last point that might seem somewhat out of place given the context of the book—if you're building separate packages that will be imported, avoid including concurrent code whenever possible.
This is not a hard-and-fast rule, but when you consider potential usage, it makes sense—let the main application handle the concurrency unless your package absolutely needs it. Doing so will prevent a lot of hidden and difficult-to-debug behavior that may make your library less appealing.