The KindSoftware Coding Standards
Table of Contents:
- Naming Conventions
- Semantic Properties
- Code Examples
- Specific Recommendations for:
Documentation is all about communication. If you have any hope or desire to see your code understood and reused, it needs to be completely and thoroughly documented. We have a tool called the "CommentCounter" that can actually evaluate the true comment volume of your code. While we'll accept code submissions with a 35% documentation ratio, around 50% is what we're really looking for.
These numbers sound high even for extensively documented classroom code, and incredibly high for Open Source Software. So where does all this documentation come from?
In-code documentation isn't all that counts toward the ratio. Overviews, design documents, man pages, etc. all contribute as well.
In our experience, once you document a system so that other programmers can both rapidly understand what you have built and be capable of building it from scratch with your design, you will have ratios close to what we have prescribed.
How much is enough?
Your guiding metric for "How much is enough?" should be the following: Communicate exactly enough information in your comments so that the reader can implement what you are describing and do so correctly.
Quality is better than quantity. We don't want to see dozens of "My dog is blue" comments in code just to bump up the numbers. Besides, the new design of the CommentCounter will catch this kind of funny business anyway.
Some argue that the code itself should be "self-documenting". This is true in some sense, and we enforce it in some ways through naming conventions and running comments, but it isn't enough. What about the reader who doesn't know the language you are coding in? What about proprietary reusable components? Obviously, something more is necessary.
We find this opinion especially among the functional programming languages community. It astounds and confuses us that such a bright group of programmers can seriously think that no documentation is better than good documentation. We're working to make a difference there as well.
Real coders don't document
Also, for those of you that think that documenting is for weaklings and that real hackers, Masters, and Rambo-coders don't need comments; believe us, we could find some code that you wouldn't understand even with days of head-scratching (if you're in the area, drop by and we'll prove it). Rambo-coders need not apply.
We use semantic properties for documenting program code is regular, parseable, meaningful ways.
Each property has a legal scope of use, called its context. Contexts are defined in a coarse, language-independent fashion using inclusion operators in kind theory. Contexts are comprised of files, modules, features, and variables.
Files are exactly that: data files in which program code resides. The scope of a file encompasses everything contained in that file.
A module is some large-scale program unit. Modules are typically realized by an explicit module- or class-like structure. Examples of modules are classes in object-oriented systems, modules in languages of the Modula and ML families, packages in the Ada lineage, etc. Other words and structures typically bound to modules include units, protocols, interfaces, etc.
Features are the entry point for computation. Features are often named, have parameters, and return values. Functions and procedures in structured languages are features, as are methods in object-oriented languages, and functions in functional systems.
Finally, variables are program variables, attributes, constants, enumerations, etc. Because few languages enforce any access principles for variables, variables can vary in semantics considerably.
We maintain regular convensions for property-based documentation for each of these scopes. They are documented in the next few sections.
Every file has a file comment contains at least the following information (example below):
- The title of the project with which this module is associated using the title property.
- A short description of the file's contents using the description property.
- Any copyright information relevant to the project using the copyright property.
- The license(s) under which the file is protected using the license property.
- The primary authors of the file using the author property.
- Using a version property, document the RCS/CVS tag $Revision: 19441 $.
A module (class, interface, package, module, unit, protocol, etc.) comment describes the purpose of the module, guaranteed invariants, usage instructions, and/or usage examples. The beginning of the comment should be a description of the module in exactly one sentence using the bon property. Also included in the class comment are any reminders or disclaimers about required or desired improvements. Use XHTML format when appropriate, but do not forget that all inline text is parsed as XHTML format by most tools, so accidental use of XHTML elements can result in strange looking documentation. See the below chart for appropriate properties and usages.
Each class comment block must include exactly one version
property and at least one author property. The
author properties often list everyone who has written more
than a few lines of the class. Each author property should
list exactly one author. The version property's version is
a project specific string (e.g. "1.0b5c7") followed by a CVS/RCS
Date$ tag. Additionally, each class may optionally
// comment after its closing brace stating that
the class declaration has ended.
Use language and local documentation conventions to describe nature, purpose, specification, effects, algorithmic notes, usage instructions, reminders, etc. The beginning of a method comment should be a summary of the method in exactly one sentence using the bon property. Use XHTML format when appropriate. Individual paragraphs within a comment do not need bounding paragraph tags (<P>). See the chart below for appropriate properties and usages.
At the minimum, variables should be commented with those semantic properties that are not implicitly specified by program structure. Many variable-scoped semantic properites are implicit within the structure of the program code given the semantics of the programming language in use. For example, the hides property, when used, is an explicit documentation of an implicit feature of the language. Thus, the most important semantic property to use on variables is the values property, each of which should also, obviously, be documented as a class invariant.