How to Create a Reusable Package in Go for Third-Party Developers

Go is a powerful language designed for simplicity and scalability. One of its standout features is the ease with which developers can create reusable packages. This guide will walk you through the process of creating a Go package that can be used by third-party developers, complete with examples.

Understanding the basics of a Go package

A Go package is a collection of related Go files that are grouped under a single directory. Each file within a package must start with the package keyword, followed by the package name. The package can then be imported and reused in other Go programs.

By convention ...

• Packages intended for general-purpose use (libraries) are named in lowercase.
• Files within the package should have related functionality.

Setting up your Go project

1. Initialize the Module Use go mod to create a module. Modules are the unit of versioning in Go, and they make your package easy to share.
2. Create Package Files Inside the mymath directory, create a file named math.go to define your package.

Writing the actual package code

Let's create a simple math package with functions for addition and subtraction.

math.go

package mymath 

// Add adds two integers and returns the result.
func Add(a, b int) int {
    return a + b
}

// Subtract subtracts the second integer from the first and returns the result. 
func Subtract(a, b int) int {
    return a - b
}        

Notice that the function names Add and Subtract start with an uppercase letter. This makes them exported, meaning they can be accessed from outside the package.

Adding package documentation

Go uses comments to generate documentation. For best practices:

• Place a comment above each exported function, struct, or interface.
• Use clear and concise language.

For example:

// Add adds two integers and returns the result.
// It takes two arguments: 'a' and 'b', which are integers.
func Add(a, b int) int {
    return a + b 
}        

You can generate documentation locally using the bash command :

go doc ./...        

Writing package tests

Go provides a built-in testing package (testing) to ensure the reliability of your code. Create a file named math_test.go in the same directory as your package.

math_test.go

package mymath 

import "testing"

func TestAdd(t *testing.T) {
    result := Add(2, 3) 
    if result != 5 {
        t.Errorf("Add(2, 3) = %d; want 5", result)
    }
}

func TestSubtract(t *testing.T) {
    result := Subtract(5, 3)
    if result != 2 {
        t.Errorf("Subtract(5, 3) = %d; want 2", result)
    }
}        

which can then easily be run using Bash with ...

Run the tests using:

go test ./...        

Making your package availabel to everyone

Once your package is ready, share it on a version control platform like GitHub/GitLab or similar.

1. Commit your code:
2. Push to GitHub (replace <url> with your GitHub repository URL):
3. Ensure your package is publicly accessible. Third-party developers can now fetch and use your package using go get:

Provide examples of use for third party developers

Make it easy for third-party developers to use your package by including examples in your README.md or a separate example_test.go file.

Usage Example

package main

import (
    "fmt"
    "github.com/yourusername/mymath" 
) 

func main() {
    fmt.Println("Addition:", mymath.Add(2, 3))
    // Output: 5

    fmt.Println("Subtraction:", mymath.Subtract(5, 3))
    // Output: 2
}        

Below are few example tests to exercise these two fimple functions.

package mymath_test

import (
    "fmt" 
    "github.com/yourusername/mymath" 
)

func ExampleAdd() { 
    fmt.Println(mymath.Add(2, 3))
    // Output: 5
}

func ExampleSubtract() {
    fmt.Println(mymath.Subtract(5, 3))
    // Output: 2 
}        

These examples will be included in the documentation and act as tests.

So in summary ...

creating a reusable package in Go can be achieved by following the few steps below.

1. Set up your Go module.
2. Write clear and concise package functions with proper documentation.
3. Add tests to ensure reliability.
4. Publish the package to a public repository like GitHub.