Show Menu
Cheatography

Golang Naming Conventions Cheat Sheet by [deleted]

A quick reference guide for idiomatic, non-idiomatic and abbreviation conventions in golang.

Why naming is important?

Critical for Readab­ility = Mainta­ina­bility
The naming is important because it is very critical for readab­ility and if you can't read the code, you can't properly maintain it.

Imagine a book that you don't unders­tand, and someone comes to you and asks you to fix the typos in it.

Can you really do it, without unders­tanding it?
There are only two hard things in Computer Science:
cache invali­dation and naming things.
- Phil Karlton

Non-Id­iomatic

func Read(buffer *Buffer, inBuffer []byte) (size int, err error) {
        if buffer.empty() {
                buffer.Reset()
        }
        size = copy(
                inBuffer,
                buffer.buffer[buffer.offset:])
        buffer.offset += size
        return size, nil
}
This code is unnece­ssarily verbose. Everything has been declared in English words, which generally should be avoided. From the readab­ility and mainta­ina­bility perspe­ctive, this code is not good.

Idiomatic

func Read(b *Buffer, p []byte) (n int, err error) {
        if b.empty() {
                b.Reset()
        }
        n = copy(p, b.buf[b.off:])
        b.off += n
        return n, nil
}
This code is very concise and idiomatic and it's easy to understand and maintain.

References

Use the first few letters of the words

var fv string // flag value

Use fewer letters in smaller scopes

var bytesRead int // number of bytes read

var n int // number of bytes read

Use the complete words in larger scopes

package file

var fileClosed bool
Imagine that this variable is declared in the package block of the  
file
  package.

It's a package level variable and therefore it's in a larger scope. Don't use abbrev­iations there and don't mix caps in the name.
file
  starts with a lowercase letter.

Use mixedCaps like this

type playerScore struct

Use all caps for acronyms

var localApi string

var localAPI string

Do not stutter

player.PlayerScore

player.Score

Do not use under_­scores oR LIKE_THIS

const MAX_TIME int

const MaxTime int

const N int
 

Abbrev­iation - Rules

Sound/­Spe­lling
Abbrev­iations should be pronou­nceable.

Abbrev­iations should have at least one vowel.

Abbrev­iations should not split up plosiv­e/l­iquid combin­ations but as plosiv­e/p­losive, for example, the  ct in dictionary or pt in caption.

Abbrev­iations should not have more than three consonants in a row and should usually end in a consonant, unless the vowel is needed for discri­min­ation, for example, alg and algo.

All of the letters in the abbrev­iation should be present in the long form and in the same order, and need not appear in sequence in the long form, for example, recv and receive.

Except­ion­s/L­imi­tations
There are a few exceptions to the above rules for common, well-e­sta­blished forms.

ct and pt can be used for ction and ption if the abbrev­iation would be too short otherwise, for example, act and opt.

There are also other types of prefixing, for example, the three-­letter prefixes used to distin­guish field names in the same database table.

Examples would include cusID for customer ID and ordID for order ID.

Those prefixes don't need to follow the same rules.

Length­/Me­aning and Interp­ret­ation
An abbrev­iation should be less than or equal to half the length of the original form.

Abbrev­iations should be at least three letters long.

Abbrev­iations should not be whole words that mean something else.

Abbrev­iations should not just consist of the prefix of a word, for example, sym for symbol or syl for syllable.

Abbrev­iations shouldn't be ambiguous. However, if the names are different that no confusion can result, they are OK.

Abbrev­iation

var a int
// array
var arg []string
// argument
var b []byte
// buffer
var b byte
// byte
var bs bytes
// bytes
var buf []byte
// buffer
var c int
// capacity
var c int
// character
var dst int
// destination
var err error
// error value
var fv string
// flag value
var i int
// index
var l int
// length
var m int
// another number
var msg string
// message
var n int
// number or number of
var num int
// number
var off int
// offset
var op int
// operation
var parsed bool
// parsed ok?
var pkg string
// package
var pos int
// position
var r rune
// rune
var r io.Reader
// reader
var s string
// string
var seen bool
// has seen?
var sep string
// separator
var src int
// source
var str string
// string
var v string
// value
var val string
// value
var w io.Writer
// writer
...the list goes on and on...
               
 

Comments

No comments yet. Add yours below!

Add a Comment

Your Comment

Please enter your name.

    Please enter your email address

      Please enter your Comment.

          Related Cheat Sheets

          GoLang fmt Printing Cheat Sheet
          GoLang Cheat Sheet