conventions

README

Conventions

Learning the syntax and semantics of a language is only the first step for new developer. The second step is learning about the language ecosystem.

Conventions is an example Go package that is loaded with documentation specifically targeting new developers that have done the Go Tour and have read the documentation on the "go" binary, but want to know more about writing packages and software.

Documentation

Overview

Package conventions is an example Go package that is loaded with documentation specifically targetting new developers that have done the Go Tour and have read the documentation on the "go" binary, but want to know more about writing packages and software.

The documentation for an entire package written here; only one of the files in a package should have it. Comments are always on the line above the thing they are documenting. Package declarations and any exports require comments that should be in the form of "Package pkgname ..." and "ExportName ..." respectively. When Go is properly commented in this way, automatic docs can be generated via the "godoc" binary or via godoc.org. For example: http://godoc.org/github.com/jzelinskie/conventions is where you can see the docs for this package, although this package was created specifically to have its source read directly.

Index

• Variables
• type Example
  • func NewExample(id int, name, description string) *Example
  • func (e Example) GetTuple() (int, error)
  • func (e Example) LastMethodCall() error
  • func (e Example) Method() (bool, error)
  • func (e Example) ShortMethod() int

Variables

var (
	// ErrStupidMistake is an example of an exported error type.
	ErrStupidMistake = errors.New("stupid mistakes are the story of my life")
)

Exported variables are usually in multi-line form, however when defining huge literals such as the constants used in cryptographic hashing algorithms, it is fine to have repeated var statements.

Types

type Example

type Example struct {
	ID          int
	Name        string
	Description string
	// contains filtered or unexported fields
}

Example is an example of how to define new types.

Fields are one-per-line and grouped together however you think is most logical. Don't worry too much about writing struct tags for every encoding under the sun. Someone can easily create a wrapper type that implements the encoding's marshaler interface (i.e. json.Marshaler).

func NewExample

func NewExample(id int, name, description string) *Example

NewExample is an example constructor for the Example type.

Constructors are always the first thing to follow the type declaration. Constructors always begin with "New" and can simply be called "New" if the name of the type being returned is the same as the package (i.e. config.New()). Returning a reference literal is better than allocating with the new keyword. Always have a trailing comma on the last item in anything multi-line; this is done to reduce diff sizes in version control systems.

func (Example) GetTuple

func (e Example) GetTuple() (int, error)

GetTuple is an example method for error handling and scopes. When a method returns error as single value, handle it in one line. When returning err is out of scope, it looks like it is going to be used in somewhere else

func (Example) LastMethodCall

func (e Example) LastMethodCall() error

LastMethodCall is an example of returning error result for the last provoked method. When last called method returns an error, there is no need to make a nil check, if there is not any special need for error handling.

func (Example) Method

func (e Example) Method() (bool, error)

Method is an example method for the Example type.

Methods are always what come after constructors. Godoc will order them alphabetically, but it is often more useful to order them logically. For most receivers, prefer pointers over values. Exceptions to this are small arrays, small structs (or structs that are natural value types), maps, functions, and channels.

func (Example) ShortMethod

func (e Example) ShortMethod() int

ShortMethod is an example of a method short enough to be kept on one line. The gofmt tool will not automatically put methods that are this short on one line, but it will not break them down into multiple lines either.