bear in mind that some of their suggestions, e.g., about naming and suggestions, are just that, and there are other ways that work well too. (it is important to be consistent though!)

i thought i'd share with you some personal experiences with style.

as a graduate student i worked on a fairly large development software project called vis, and we developed our own naming convention, and associated documentation system for vis.

vis was written in C. it was broken down into "packages" each of which consisted of a set of source and header files. the packages had short suggestive names, e.g., mc for model check, ntk for network.

the naming convention roughly was the following:

the name of an exported function from a package (e.g., mc) would start with Mc_ then would come a "subject", e.g., Formula, then "action", e.g., StaticSemanticCheck, so the function name would end up being Mc_FormulaStaticSemanticCheck.

we had similar naming conventions for structs, enums, etc.

some, but relatively little, of this naming was an artefact of using C as opposed to C++. however, it was EXTREMELY useful - when i needed a function from a package someone else wrote, i wouldn't have to scan a list of scores of functions trying to figure out what each one did.

another very nice feature of this naming convention was that we wrote "structured comments" with each function/struct/enum/etc. we had a perl script then go in to the source code and build a set of html pages which documented the code, with links between the related functions.

take a look at the following URLs for examples:

www-cad.eecs.berkeley.edu/~vis/doc/html/packages.html

(click on a few links to see examples, e.g., www-cad.eecs.berkeley.edu/~vis/doc/html/mcExt.html

the "vis engineering manual" describes the the naming convention and its justification:

www-cad.eecs.berkeley.edu/~vis/doc/VisEngineering/vis_eng/vis_eng.html

the ext system which we used to generate the html documentation from the naming convention and structured comments is available at

www1.cs.columbia.edu/~sedwards/ext/index.html

the best documentation system iknow of now doxygen. it is more robust, and produces documentation in may forms (html, doc, latex, etc.). as an example, you can take a look at what the final product can look like by seeing mozilla's internal documentation.