Skip to content

Instantly share code, notes, and snippets.

Last active Jun 4, 2017
What would you like to do?
Documentation Conventions

Prefer present tense


This function will update the value


This function updates the value

Motivation: To be consistent and avoid switching tenses. Present tense is slightly more concise to write. It also avoids implying something hasn't been implemented yet.

Prefer singular


Arithmetic instructions update destination registers


An arithmetic instruction updates its destination register

Motivation: When there are direct objects, this avoids ambiguity about the number. If the subject is plural, the object must be plural, and it is unclear whether there is a one-to-one or one-to-many relationship.

Use third person to describe activities. The subject is the program/hardware.


We load a value from memory

You load a value from memory

I load a value from memory


The cache loads a value from memory

Motivation: consistency, gives the option to be more specific about what subsystem/function is performing the action.

Meaningless words and phrases to avoid or simplify

  • Note that/It should be noted -> eliminate
  • It is possible for X -> may X
  • Actually/Technically -> eliminate (most adverbs, actually)

For commments and lists that describe algorithms, use imperative mood, as if you are telling the program what to do


This adds values together and writes back the result


Add the values together and write back result

Motivation: Consistency. The imperative mode is more direct and concise.

Other references

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment