Page 232 - The Art of Designing Embedded Systems

A Firmware Standards Manual 2 19

Precede and follow comment blocks with semicolon lines:

; Comment block that shows how comments stand
; out from the code when preceded and followed by
; “blank“ lines.

Never run a comment between lines of code. For example, do not
write like this:

mov rl, r2 ; Now we set rl to the value
add r3, [data] ; we read back in read-ad

Instead, use either a comment block, or a line without an instruction,
like this:

mov rl, r2 ; Now we set rl to the value
; we read back in read-ad
add r3, [datal
Be wary of macros. Though useful, macros can quickly obfuscate
meaning. Do pick very meaningful names for macros.

Tools
Computers

Do all PC-hosted development on machines running Windows 95 or
NT only, to insure support for long file names, and to give a common OS
between all team members.
If development under a DOS environment is required, do it in a Win
95/NT DOS window.
Maintain every bit of code under a version control system. In addi-
tion, the current compiler, assembler, linker, locator (if any) and debug-
ger(s) will be checked into the VCS. Products have lifetimes measured in
years or even decades, while tools tend to last months at best before new
versions appear. It’s impossible to recompile and retest all of the product
code just because a new compiler version is out, so you’ve got to save the
toolchain, under VCS lock and key.
The only downside of including tools in the VCS files is the additional
disk space required. Disks are cheap; when more free space is required sim-
ply buy a larger disk. It’s false economy to limp by with inadequate disk
space.