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­bil­ity
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 byte­sRead int // number of bytes read
var n int // number of bytes read

Use the complete words in larger scopes

package file
var file­C­losed bool
Imagine that this variable is declared in the package block of the  ­­fil­e­  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. fil­e­  starts with a lowercase letter.

Use mixedCaps like this

type pl­aye­r­Score struct

Use all caps for acronyms

var local­Api string
var local­API string

Do not stutter

playe­r.­Pl­aye­r­Score
pla­yer­.S­core

Do not use under_­scores oR LIKE_THIS

const MAX_­TIME int
const MaxT­ime int
const N int
 

Abbrev­iation - Rules

Soun­d/S­pel­ling
Abbrev­iations should be pronounceable.

Abbrev­iations should have at least one vowel.

Abbrev­iations should not split up plos­ive­/li­quid combin­ations but as plos­ive­/pl­osi­ve, for example, the  ­ct in dict­ion­ary or pt in caption.

Abbrev­iations should not have more than three conson­ants in a row and should usually end in a conson­ant, 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 rece­ive.

Exceptions/Limitations
There are a few exceptions to the above rules for common, well-e­sta­blished forms.

ct and pt can be used for ­c­tion 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/Meaning 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 shou­ldn't be ambigu­ous. However, if the names are different that no confus­ion can result, they are OK.

Abbrev­iation

var a int
// array
var arg []string
// arg­ument
var b []byte
// buffer
var b byte
// byte
var bs bytes
// by­tes
var buf []byte
// buffer
var c int
// ca­pacity
var c int
// ch­aracter
var dst int
// ds­t­ination
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
// ms­age
var n int
// number or number of
var num int
// number
var off int
// offset
var op int
// op­eration
var parsed bool
// parsed ok?
var pkg string
// pa­c­k­age
var pos int
// pos­ition
var r rune
// rune
var r io.Reader
// reader
var s string
// string
var seen bool
// has seen?
var sep string
// sep­arator
var src int
// so­u­rce
var str string
// string
var v string
// value
var val string
// value
var w io.Writer
// writer
...the list goes on and on...
               

Help Us Go Positive!

We offset our carbon usage with Ecologi. Click the link below to help us!

We offset our carbon footprint via Ecologi
 

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