codestyle.txt

--- Go Code Style Guidelines ---


Identifier Prefixes

runXyz - package goroutine function
   go runXyz(...)

Since the scope of lowercase identifiers is important but 
impossible to infer, we use these conventions for clarity in 
non-exported terms. 

pPackage - package outside the standard library
   import pWs "github.com/gorilla/websocket-1.2.0"
tType - package/function type
   type tStuff struct {...}
_func - function private to its file or type
   func _thisFileOnly() {...}
   func (o *tStuff) _thisTypeOnly() {...}
kConst - package/function constant
   const kDumbPi = 3.142
eConst - package/function enumerated constant
   const ( eClassOne=iota; eClassTwo; eClassThree; )
sVar - package variable (s = static)
   var sWhat []string
aVar - function variable; exceptions: err & ok return values
   aFile, err := Open(...)
   for a := 0; a < kMax; a++ { // instead of i
      for a1 := range ... {    // instead of j
iVar - function argument (i = input)
   func xyz(iWhat, iWhere string) {...}
o - function receiver argument, fka "this" (o = object)
   func (o *tStuff) Xyz()
   func runXyz(o *tStuff) // go a.runXyz() not allowed
fFunc - "closure", usually passed as callback
   fDone := func() {...}
cVar - closure variable or argument
   fSum := func(cNum int) { cSum := cNum + aNum }

Since these are recognized by context, no prefix for:

fmt.Printf() - standard library package
a.v - struct member
youNameIt() - package function

In a multi-file package, package-level functions that 
are meant for use beyond their file (i.e. don't start with _) 
begin with a verb and end with the name of the file.
   func flyBird() // defined in bird.go


Organization

Package constants and variables appear at the top of their source 
files, followed by func init() (if used).

Type and function definitions appear roughly in order of invocation 
in source files. Types are defined before any methods for them, but 
usually after any factory functions. Definitions therefore usually 
appear after first use. 


Format

go fmt is barred, as it destroys useful 1-line constructs.

Indents are 3 spaces.

Since this is ubiquitous, it goes on one line:
   if err != nil { quit(err) } // or other abort function

Columnar alignment for adjacent similar lines
   a.x =  aB.x.y
   a.y = &aB.x.z
or
   func (o string) bang()      byte { return o[0  ] }
   func (o string) ohi (i int) byte { return o[i+1] }
or
   case 1: a = "one"
   case 2: a = "two"

Dense conditionals
   if a {
      stuff()
   } else {
      other()
   }

Since we can't write:
   v = t ? a : b
we say:
   v = b; if t { v = a }

We would like to write this, but the compiler interferes:
   if t { a() }
   else { b() }

We would like to write this (allowed in Javascript):
   func f() {
      call(fCb)
      func fCb() { ... }
   }


Consider the API

All package-level functions, exported and private, belong to an API, 
which must be coherent.

Do not create single-caller package-level functions simply to make 
the caller easier to read, as this typically pollutes the API.