Joe's Engineering Principles

Joe Clark ~~ May 25, 2003 / Jan 23, 2004

Okay, after being in the systems engineering world for a couple years now, I have begun to collect some opinions on how things are done. I would like to share them for you here. I will add to this list as I gain more experience.

Document Principles (1/23/04)

1) Every document needs a well-known "home" filesystem location (what good is a document if you can't find it).
2) In general, every piece of data needs to have a home in a single well-defined document (redundant data is inherently hard to keep up to date).

Guess the Interface Principle

If part of the interface design is known, then other related parts of the interface should also be known by following common sense rules.

Corollaries:

Common Prefix/Suffix Corollary

When part of an interface uses a particular prefix or suffix, the entire interface should use that same prefix or suffix (where appropriate). Ex: examine errno.h. Each error identifier begins with "E".

Related Syntax Corollary

When an interface consists of two or more items that are related (transmit and receive, for example), the same style should be used for all related items (ie, transmitData -> receiveData, *NOT* rxData, *NOT* rx_data, *NOT* RxData)

Common Variable Style Corollary

If some parts of an interface use a particular variable naming style, all parts of the interface should conform to the same style. Ex: if one variable is transmit_data, the matching function should be receive_data, *NOT* receiveData.

HappyMad Principle

When a hard-to-track bug is finally tracked down, the one who finds it experiences "happyMadness" that is proportional to the time spent searching for the bug. HappyMad is so named because the finder is happy that the bug has been found, but mad that the bug existed and was difficult to track down.

Wrong Comments are Evil Principle

It's hard to keep comments valid. Things change, and when they do we recompile our code to make the code work. When the code works, we forget to update the comments. This is a Bad Thing. If comments are wrong, they are of little value, since their content cannot be trusted. Of course some comment differences (different nomenclature for the same variable, etc) are minor, but I think the goal should still be to have the comments exactly match the code, for "beautification" purposes.