Whitepapers
The KindSoftware Coding Standards
Table of Contents:
- Introduction
- Documentation
- Naming Conventions
- Semantic Properties
- Tools
- Code Examples
- References
- Specific Recommendations for:
- 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:
|
[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:
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 wait s (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. |