Page 229 - The Art of Designing Embedded Systems

216 THE ART OF DESIGNING EMBEDDED SYSTEMS

should be possible to get a sense of the system’s operation by reading only
the comments.
Explain the meaning and function of every variable declaration.
Every single one. Explain the return value, if any. Long variable names are
merely an aid to understanding; accompany the descriptive name with a
deep, meaningful, prose description.
Comment assembly language blocks and any line that is not crystal
clear. The worst comments are those that say “move AX to BX’ on a
MOV instruction! Reasonable commenting practices will yield about one
comment on every other line of assembly code.
Though it’s useful to highlight sections of comments with strings of
asterisks, never have characters on the right side of a block of comments.
It’s too much trouble to maintain proper spacing as the comments later
change. In other words, this is not allowed:
.................................................
* This comment incorrectly uses right-hand *
* asterisks *
.................................................

The correct form is:
.................................................
* This comment does not use right-hand
* asterisks
..................................................

Coding Conventions

No line may ever be more than 80 characters.
Don’t use absolute path names when including header files. Use the
form #include <module/name> to get public header files from a
standard place.
Never, ever use “magic numbers.” Instead, first understand where the
number comes from, then define it in a constant, and then document your
understanding of the number in the constant’s declaration.

Spacing and hdentation

Put a space after every keyword, unless a semicolon is the next char-
acter, but never between function names and the argument list.