What is Example Function in Go?

As a programmer, you need to understand exactly what example functions are and how to use them to build maintainable software.

What is Example Function?

Example functions in Golang are testable pieces of code that you can add to your package for documentation and verification of accuracy. Example functions do not take parameters and return no results.

Imagine you have a Multiply function in your project:

func Multiply(a, b int) int { return a * b }

An example function for Multiply would look like this:

func ExampleMultiply() {
fmt.Println(Multiply(4, 5))
// Output: 2
}

Example functions use a similar naming convention for software testing. Define a function instance by adding the function's name to Example, like the field with ExampleMultiply here.

Learn more about example functions in Go

The code in the previous section shows the basic structure of the example Function. What makes up an example is the name, function content, and the comment at the end of the function.

When output comments are added, Go compiles and executes the example to verify its correctness, but without comments Go only compiles the example function, not executes it.

1. You can define an example for the package, just call the Example() function without the suffix. For example, here is a package level example.

func Example() { fmt.Println("Hello, world!") // Output: // Hello, world! }

2. To define example for a function, you simply add the function name as a suffix as learned earlier.

func ExampleMultiply() { fmt.Println(Multiply(4,5)) // Output: 2 }

3. To identify example for a type, add the name as a suffix to Example . For example:

type MyStruct struct { // . } func ExampleMyStruct() { // . }

4. Finally, for a method on a particular type, you add the type name, an underscore, then the method name. For example:

func (m *MyStruct) MyMethod() { // . } func ExampleMyStruct_MyMethod() { // .

You can specify multiple examples for an entity by adding an underscore and a suffix that begins with a lowercase letter. For example: ExampleMultiply_second , ExampleMyStruct_MyMethod_second .

You can also use a larger example to explain complex logic using the whole file example.

The Go engine recognizes and handles example functions the way you define them.

Document code using example function

The Example function is useful for both documentation and testing purposes. Example functions often do a better job of explaining behavior than commented functions.

Just like Java's Javadoc, Go's built-in documentation tool, godoc, makes writing documented code a breeze. However, you'll want to document some of the libraries and functions together to better understand how they work. Example functions eliminate this drawback because they can demonstrate interactions between different units in the package.

The godoc tool automatically associates examples with the function, type, and package they belong to, depending on your requirements. It also goes a step deeper by allowing testing within the document web interface.

You can try out a package or method right in the document, even before you use it in code.

This image shows an example of the json.Valid function in encoding/json :

Above are the basics you need to know about example functions in Go. Hope the article is useful to you!

Isabella Humphrey

Update 17 October 2023