Coding Standards

By Ivan Gevirtz

created: Thursday, October 06, 2005
updated: Monday, January 07, 2008

The goal of coding standards are to increase the business value of the code.  The most obvious (and indeed most important) way to do this is to make the code robust and low defect.  Equally important, but more subtle goals include reducing coder friction and maintainability.  As such, standards should be kept minimal -- simple enough to actually follow, and important enough to remember.

These standards should be used when building new source files.  When an existing file needs to be changed, that is an appropriate time to bring it up to standard.  However, it's never a good time to edit a file merely to bring it up to standard.  If it ain't broke, don't "fix it" and remember to always "Keep it Working".

You'll notice that I don't touch on the classic "Religious" points:

Consistency within a file is important and improves readability.  But allowing coders to express themselves is also important.  So, if you edit a file, either conform to the religion of that file, or convert the whole file to a new, consistent format.  If you convert the whole file, you are effectively taking ownership of it, so be prepared to be the go-to person, or leave it as is.

General Rules:

Good code is:


Comments are generally a good thing.  If you think your code needs a comment, it probably does.  I used to be crazy about comments, but my thoughts have changed.  Good code is self commenting, with good names for functions, methods, classes, and variables.  Functions and methods are verbs, variables and members are nouns.  Coding constructs are used to help clarify what's going on, and the expressiveness of the language is judiciously used to even further clarify.  For example, do...while is used rather than a primed while when you want the reader to know it will always execute once.  Cute or hard code is avoided, or commented.  Maintain an appropriate scope with your comments including interfaces, tests, and non-local changes. Describe why you wrote the code, not how you wrote it.

The major problem with comments is duplication of information.  Comments should not duplicate what the code says.  Later in life, the code will change, and the comment won't.  Programmers will read the comment and be mislead, bad bad bad!  Instead, comments should clarify the reasons for the choices the code implements.  Why use a polling loop vs. a callback architecture?  Why are you discarding that buffer periodically, when there appears it may still have salient data?

In the rare event where the code really is obtuse, and you can't figure out how to make it clearer, then a comment block may be required.  However, in this case it is best to indicate that this is a good candidate for refactoring.  For the occasional code that has to be obtuse (e.g.. for real-world performance tuning), indicate as such.  And make sure there are great Unit Tests exercising all the functionality!


Format Standards:

Defensive Coding Conventions


C++ Defensive Coding Conventions

 Hungarian Notation, Name Decoration:

Personally, with the few exceptions mentioned in "Naming" above, I'm not a fan.  With modern tools, such as what we use (Visual Studio), types are easily discerned by hovering the mouse pointer.  Changing the type of a variable and then having to change the name everywhere in the code is problematic.  And Hungarian notion mandates duplication of information, which leads to synchronization problems, such as when the type changes and the name doesn't.  As such, you can never rely on the notation, and so it is just cumbersome and makes things less readable (how many extraneous letters are prepended until I know what the descriptive variable name is?).  Hungarian Notation was intended to indicate the kind, not the type, and this may have some utility, such as distinguishing pointers from simple data types.  However, some people like this, and in the spirit of consistency, try to be consistent within a file.

UPDATE (10/14/05):  The Hungarian notation described in the various "Clique Coding Standards" documentation is what I'm talking about.  Adding prefixes which describe the storage type of a variable is inane.  On the other hand, using prefixes to describe the kind of data represented by the variable is useful.  The following are useful Hungarian Notation conventions, and are worthy of consideration:

p     pointer

b     True/False

sz    Null terminated string

cb    count of bytes

cch   count of chars

cw    count of words

and the like...  However, if we decide to adopt this, we should remove the storage type of Hungarian notation, as it is confusing, and contradictory.  If we are to use Hungarian notation, we need to make it a company policy, for its utility is only realized when all the code conforms.  Incomplete or incompatible conformity makes things worse.  Here is an interesting link describing the differences between the useful kind of Hungarian notation and the asinine type.