Skip to content

Instantly share code, notes, and snippets.

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

Prefer present tense

No:

This function will update the value

Yes:

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

No:

Arithmetic instructions update destination registers

Yes:

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.

No:

We load a value from memory

You load a value from memory

I load a value from memory

Yes:

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

No:

This adds values together and writes back the result

Yes:

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