Comments.md

title
Comments

Every package should have a package comment. It should immediately precede the package statement in one of the files in the package. (It only needs to appear in one file.) It should begin with a single sentence that begins "Package packagename" and give a concise summary of the package functionality. This introductory sentence will be used in godoc's list of all packages.

Subsequent sentences and/or paragraphs can give more details. Sentences should be properly punctuated.

// Package superman implements methods for saving the world.
//
// Experience has shown that a small number of procedures can prove
// helpful when attempting to save the world.
package superman

Nearly every top-level type, const, var and func should have a comment. A comment for bar should be in the form "bar floats on high o'er vales and hills.". The first letter of bar should not be capitalized unless it's capitalized in the code.

// enterOrbit causes Superman to fly into low Earth orbit, a position
// that presents several possibilities for planet salvation.
func enterOrbit() os.Error {
  ...
}

All text that you indent inside a comment, godoc will render as a pre-formatted block. This facilitates code samples.

// fight can be used on any enemy and returns whether Superman won.
//
// Examples:
//
//  fight("a random potato")
//  fight(LexLuthor{})
//
func fight(enemy interface{}) bool {
  ...
}