Coding Style versus Coding Standards

 One important point that I think should be brought up right away is
 that there is an important distinction between a document on `Coding
 Standards' and one on `Coding Style'.  In particular, I think that it
 is a very good idea for Akamai to come up with guidelines for good
 coding practices, but I think that it is NOT a good idea to come up
 with an enforced coding style.

 Coding Standards documents should include guidelines about
 conventions for arranging and documenting code, practices for
 avoiding common pitfalls and mistakes, and strategies for providing
 features not included directly by the language (such as multiple
 header file inclusion and strong error checking).  They document and
 encourage `best practices', and often serve as the only real
 documentation for site-specific practices (such as the `akamai
 logging library').

 Coding Style documents are concerned with how the code for a given
 language is formatted, including the pernicious task of determining a
 `correct' use for whitespace.  Examples include `newlines before
 function declarations?', `newlines between parameters in function
 declarations?', `newlines before and/or after braces in code
 blocks?', and `spaces before and/or after operators, builtins, and
 function calls?'  Often coding standards will discuss indenting as
 well, including the use or not of hard tabs and the `correct' level
 of indentation of various features of a language.

 Coding Standards documents are helpful for newwer and less
 experienced programmers working alone, and helpful for programmers of
 all levels working in groups.  They increase readability and
 cooperation, and often lead to `cleaner', more `elegant' code.
 Correctly done, they have little negative impact.  In short, they are
 `good'.

 Coding Style documents are helpful for improving the readability of
 code -- if the style chosen is readable to all invovled.
 Unfortunately, they enforce decisions that are largely arbitrary,
 and, to some, intolerable.  The central arguments that are typically
 addressed by coding standards are older than most Akamai employees,
 and show no sign of halting.  They provide little real benefit and
 have a high potential for negative impact on programmers.  They are
 one of the largest sources of contention in any large project, and
 are sparingly employed because of it.  Automated tools for enforcing
 coding styles exist, and are known to cause (sometimes severe)
 problems.  Small, diverse groups tend to employ them only after long,
 frequently reoccurring debates.  Large groups tend to create and then
 ignore them (IBM, Microsoft, HP, and Digital all fall into this
 category).  In short, they are `not good'.

 To summarize:

 Creating a coding standards document is a great idea.  It will give
 us some clear documentation for things that many people have been
 mistakenly taking for granted, and will be an excellent resource for
 new people.

 Creating a coding style document is a less good idea.  A mandatory
 coding style document is a difficult, unforgiving, and reviled task
 with little positive outcome.  A nonmandatory coding style document
 will provide a guideline for new programmers, but will be ignored by
 seasoned programmers, who include the ability to code in the `current
 style of the code' as an important skill already.  Thus, while there
 is positive benefit, it seems unlikely to be worth the time
 investment at this point.