Whitepapers

The KindSoftware Coding Standards

Table of Contents:

1. Introduction
2. Documentation
3. Naming Conventions
4. Semantic Properties
5. Tools
6. Code Examples
7. References
8. Specific Recommendations for:
   1. Java
   2. Eiffel
9. Credits

Semantic Properties

Semantic properties (or just "properties" for short) are our generic way of talking about special purpose documentation used to "tag" program structures. Examples of documentation properites include Javadoc tags and Eiffel indexing properties. Thus, if you are a Java programmer, read "property" as "tag"; if you are an Eiffel programmer read it as "index property" and "well-structured comment".

Semantic properties, as discussed in two papers: Semantic Properties for Lightweight Specification in Knowledgeable Development Environments and Semantic Component Composition.

Properties values that are strings should be enclosed in double-quotes ('"'). Strings that are split across lines should use the percent continuation character ('%'). See the example files and headers for examples.

In all of the following properties, Expression means (predicate | code segment | natural language description). A predicate is a boolean-valued function. Examples of valid predicates for detailed specification purposes include expressions written in specification languages like BON, JML, and the Object Constraint Language, or traditional predicates in any normal (predicate) calculus or (boolean, Hoare) logic. A code segment is a legal expression from any programming language, but is most often written in the language of the code it documenting. A natural language description is a description written in a spoken language (like English).

For all properties, entities enclosed in () or <> must be so enclosed when using the properties. E.g. "(Expression)" means literally "(" + the expression + ")". Entities enclosed in [] in the table are optional, and should not be enclosed in literal square brackets when present.

The table lists, in the "Usage" column, the programmatic constructs to which each property is applicable. Possible values for this column are files, modules, features, variables, all, and special. Special usages are explained in the "Purpose/Description" column. We provide a map of these constructs to each programming language for which we go into greater detail later in this document.

Property Conventions

The following table documents all properties and their usages.

Property	Usage	Purpose/Description
Meta-Information
author Full_Name	Modules	Lists an author of the module. The text has no special internal structure. A doc comment may contain multiple author properties. A standard author property includes only the full name of the author and should not include other information (like an email address, web page, etc.) unless absolutely necessary.
bon BON summary of construct.	Modules, Features	Provides a one-sentence summary of the construct. This sentence is meant to corrolate with the BON specification of the construct.
bug Description	Modules, Features	Describes a known bug in the module or feature. One property should be used for each bug. If a construct has a known bug, it should be described. Omission of a bug description is considered as bad an offense as the existence of the bug in the first place.
copyright Copyright	Files	A copyright notice.
description Description	Files	A brief description of a file.
history Description	All	Describes how a feature has been significantly modified over time. For each major change, the description should include: who made it, when it was made (date and version), what was done, why it was done, and a reference to the change request and/or user requirement that resulted in the change being made.
license License	Files	A license notice.
title Title	Files	Documents the title of the project with which the file is associated.
Pending Work
idea Author [Classifier] - Description	All	Describes an idea for something from the named user. The optional "Classifier" argument is for ad hoc categorization of ideas. Typical examples include optimizing algorithms, proving correctness of new code, renaming variables or features to conform to standards, cleaning up code, etc.
review Author - Description	All	Suggests/Reminds a reader that a particular block of code still needs to be reviewed (by the named user) for some reason. Typical reasons include the "something's not right here" syndrome, boundary condition checks, not understanding an algorithm completely, etc.
todo Author - Description	All	Describes some work that still needs to be accomplished by the named user. Typical examples include optimizing algorithms, proving correctness of new code, renaming variables or features to conform to standards, cleaning up code, etc.
Formal Specifications
[label:] ensures (Expression) [<Exception> -] Description	Features	Describes a postcondition that is true after a feature has completed successfully. If a postcondition is violated, then "Exception" is raised. One property is used for each postcondition. Note that no requirement is made on the visibility of postconditions, thus these are often used as the private, development specifications of a feature. The visibility of a postcondition is exactly the visibility of the feature to which it is bound. Acceptable synonyms for "ensures" are "postcondition", "post", and "ensure".
generate (Expression) [Description]	Modules, Features	Describes new, possibly unreferenced, entities (for example, new threads of control) constructed as a result of the execution of a feature or the instantiation of a module.
invariant (Expression) [<Exception>] Description	Modules, Features	Specifies a module or feature invariant. An invariant is an expression that must evaluate to true whenever the entity being described is in a stable state. An invariant expression must evaluate to a boolean. An object is defined as being in a stable state when either (a) no threads of control are within the object or operating upon the object, (b) a single thread of control is about to enter a feature of the object, or (c) a single thread of control is about to exit a feature of the object. If an invariant is violated when an object is in a stable state, a "Exception" is raised.
modify (SINGLE-ASSIGNMENT | QUERY | Expression) Description	All	Indicates the semantics of a construct as follows: SINGLE-ASSIGNMENT indicates that the construct will be set or operated upon exactly once. Once the variable is set or the feature is called, it will never be set or called again. QUERY indicates that the construct is read-only and has no side-effects. Expression indicates that a feature modifies an object and describes how it does so.
[label:] requires (Expression) [<Exception> -] [Description]	Features	Describes a precondition that must be true before the feature can be safely invoked. One property is used for each precondition. If a precondition is violated then the "Exception" is the result. The visibility of preconditions follows the same rules as the visibility of postconditions. Acceptable synonyms for "requires" are "precondition", "pre", and "require".
Concurrency Control
concurrency (SEQUENTIAL | GUARDED | CONCURRENT | TIMEOUT <value> <Exception> | FAILURE <Exception> | SPECIAL) [Description]	Modules, Features	Describes the concurrency strategy and/or approach taken by (necessary for) the module or feature. The execution context for a feature should be described at this point. The meanings of the possible parameters are as follows: SEQUENTIAL means that callers must coordinate so that only one call/access to the object in question may be outstanding at once. If simultaneous calls occur, the the semantics and integrity of the system are not guaranteed. GUARDED means that multiple calls/accesses from concurrent threads may occur simultaneously to one object in question, but only one is allowed to commence; the others are blocked until the performance of the first operation is complete. This is the behavior of synchronized instance methods in Java. CONCURRENT indicates that multiple calls/accesses from concurrent threads may occur simultaneously to the object in question, and that all will proceed concurrently with correct semantics. This is the default behavior of Java methods and fields and Eiffel features. TIMEOUT <value> indicates that if a call to this feature is blocked for a time period greater than or equal to <value>, the exception <Exception> will be raised. The value is specified with units. FAILURE means that if a call to the feature is currently underway, all additional calls with fail and the exception <Exception> will be raised. SPECIAL indicates that the feature has concurrency semantics that are not covered by the preceding cases. Make sure to explain the particulars of the feature's semantics in sufficient detail that the reader will be quite clear on your feature's unusual semantics. A feature lacking a concurrency property is considered CONCURRENT. The semantics description is optional on features that are labeled as SEQUENTIAL or GUARDED. In general, all features should have concurrency properties.
Usage Information
param parameter-name [WHERE (Expression)] Description	Features	Describes a feature parameter. The description may be continued on the following line(s). The expression indicates restrictions on argument values. Restrictions that result in exceptions, for example IllegalArgumentException in Java, should be indicated as such. In particular, it is important to indicate whether reference arguments are allowed to be null. There must be one param property for each and every parameter to the feature.
return Description	Features	Describes a feature's return value. The description may be continued on the following line(s). If the feature being documented is a simple getter feature (or similar), a return property is still necessary; however, in such a case, the actual feature description may be omitted since the return property completely describes the feature.
exception ExceptionName [IF (Expression)] Description	Features	Describes an exception that can be raised by the feature, and the circumstances under which it is raised. The guard indicates restrictions on argument values. In particular, it is important to indicate whether reference arguments are allowed to be null. There must be one exception property for each and every exception declared to be raised by the feature. In Java, for instance, a RuntimeException or IllegalArgumentException declared in the feature signature must be documented with this tag. It is generally a good idea to declare in the feature signature any runtime exceptions that are raised as a result of conditions controllable at compile-time (such as the feature being called in the wrong system state, or a lack of sufficient range checking on passed argument values).
Versioning
version Version-String	Files, Modules	Denotes the version of the construct. The text has no special internal structure. Any construct may contain at most one version property. The version property normally refers to the version of the software project that contains this construct, rather than the version of this particular construct.
deprecated Reference to replacement API.	All	Indicates that this API element should no longer be used even though it may continue to work. By convention, the text describes the API (or APIs) that replace the deprecated API. Be as specific as necessary to differentiate between overloaded or polymorphic options. If the API is obsolete and there is no replacement, the argument to deprecated should be "No replacement".
since version-tag	All	Indicates the (release) version number in which this construct first appeared. This version number, like that for the version property, is usually a project-wide version number rather than a version number for the particular construct in which the documented construct appears. No since property is required for features that have existed since the first version of the project. Often the cvs tag for a version is used here for the version-tag, but this is not a requirement. Note that current versions of cvs do not permit tags with periods (e.g. "0.1.0" is illegal).
Inheritance
hides FeatureName [Description]	Variables	Indicates that a particular variable hides a variable in a enclosing context (e.g., a parent class or enclosing module).
overrides FeatureName [Description]	Features	Indicates that a particular feature overrides a feature in an enclosing context (e.g., a parent class or enclosing module). If the overriding feature does not either call or implement a superset of the semantics of the feature it overrides, its effects must be documented (using precondition, postcondition, and invariant properties and the feature description, as appropriate).
Documentation
design Description	All	Provides information about design decisions you have made and/or useful things to know about parts of your code.
equivalent (Expression | Code Reference)	Modules, Features	Documents convenience or specialized features that can be defined in terms of a few operations using other features.
example Description	All	Provides one or more examples of how to use a construct.
see APIName Label	All	References the reader to other related material. Some source processors use this information to generate hyperlinked documentation. APIName can be the name of a Language API or an HTML anchor. This property is often used to reference an external document that describes pertinent business rules or information relevant to the source code being documented. The character `#' separates the name of a module from the name of one of its features. One of several overloaded features may be selected by including a parenthesized list of argument types after the feature name. Whitespace in see's modulename is significant. If there is more than one argument, there must be a single blank character between the arguments. See the pieces of example code for examples of use. A comment may contain multiple see properties.
Dependencies
references (Expression) [Description]	Modules, Features, Variables	Indicates that the construct references other constructs like objects, instances, files, etc. This is primarily used to indicate subtle inter-dependencies between modules, features, etc.
use (Expression) [Description]	All	Indicates exactly those elements that are utilized by this element. This property is primarily used to indicate hidden dependencies.
Miscellaneous
guard (Expression) [Description]	Features	Indicates that actions use guarded waits (e.g. in Java Object.wait()) until the condition specified in Expression holds.
values (Expression) [Description]	Variables	Describes the possible values of a variable, including ranges and/or distinct values.
(time|space)-complexity (Expression) [Description]	Features	Documents the time or space complexity of a feature. Expression should be in big-O notation. E.g. O(n*n) and O(n^2) are equivalent, but the second is the more normal way to express a square term. The free terms of the expression should be documented in the description; usually, they are related directly to instance variables of the surrounding or related classes or modules.