Hints for coding style guide
To me, a coding style guide is a writers guide, similar to what you'd see used with publications. It is part of how a design is communicated (specs, requirements and, architecture) an implementation is communicated. Communication of its implementation (coding style, comments, review) its testing, what can be expected of it (the code).
Although there may be different coding style guides for different projects, each guide typically covers such things as:
- Conventions for consistency, especially where variations are deadly
- Conventions for clarity to other people (e.g Go lightly on the XOr's)
- Conventions for clarity to the compiler and machine
- Constraints (things you shouldn't do unless you need to)
- Naming conventions. How should you name folders, files, variables, types and so on? It seems so arbitrary, but there are competing styles, each with good (and so-so) reasons for why their name formats are used.
- Preferred types and type names what types to use
- How to name types when you define your own
- How to avoid common mistakes, obvious don't dos
- Subtle traps
- Files. A description of a files should have a defined sizing rule. Should everything go into a single file? Should a file generally be less than 2000 lines? 200? Should it be just a minimum of a procedure or variable?
- Procedures or other units. How should they be named? How should they be described? How big should they be? How should they be broken up?
Some of the goals are to allow code analysis or review by engineers on other software teams.
Another is to help allow automated analysis or testing. But another is the role of a style guide in process (_what_ are you trying to communicate with process?), a topic I may ponder in the future.
Other Coding Style Guide
It can help to study other style guides (or refer to them). Below are a couple.
Multics Coding Standards
I can't recall a Unix style guide per se, but I believe each org (e.g. HP, Bell Labs) had one. You may wish to contrast this with GNU's guide
and the 'non' guide
Michael Barr sells a coding standard, but it seems more like a power point presentation for his consulting or a starting outline of what some of a style guide would contain, rather than full, representative style guide. But it is also a good read.
I'll be coming back to this in the future entries.