Version 1.9 Build 1556

News	FAQ
Search	Home

Next: Coding Up: Standards and Guidelines Previous: Code Organization

Subsections

Documentation and Naming

Documentation in Header Files

Header files shall contain clear and complete documentation for classes and modules. Templates (or ``boilerplate'') for these files are code/install/codedevl/template-class-h and template-module-h. That directory also has templates for other standard kinds of files.

Documentation in Implementation Files

Background, usage, and overall design is presented in class header files, and implementation files do not need to repeat them. But non-obvious sections of code do need to be accompanied by explanation, including references to manuals or texts as appropriate. ``Obvious'' is to be judged from the perspective of a competent programmer, generally knowledgeable - but not necessarily expert - in the program domain. The guiding principle is: do not force those who read your code to spend unnecessary time deciphering it. It will always be a net savings of time if you document what you have done, and why you did it.

Names for Classes, Functions and Variables

All class, function and variable names will reflect a balance between clarity and convenience, with clarity having priorty. Idiomatic abbreviations, acronyms and contractions are discouraged. Names for classes, structures, and enumerated types shall begin with an uppercase letter. Identifers which consist of more than one word (a recommended practice) shall use uppercase at the beginning of each new word (``GoodClassName''). Local variables, class data members, class member functions, and global functions names shall begin with lowercase letters (``goodVarName, goodFunctionName''). Class data members shall have names prepended by its, or postpended with _p (``itsCount, blockPointer_p'').

Note: Glish function names follow a different policy: they shall use lower case letters exclusively.

Names for Files

The only restrictions here are commonsense, and the Unix library archive utility ``ar''. It is strongly suggested that the file name equals the name of the one or dominant class in the file. The above suggests that file names should be long enough to convey meaning to the reader, but not so long as to be a burden to type. This translates to: file names should be from about 8 to about 30 characters long.

``ar'' requires that all object file names be unique in the first 14 characters.

Underscores are not allowed in file names.

Any file (a shell script, or a C++ program, for example) which can be invoked at the command line as an executable program, must be named with lower case chararacters only. (This policy follows the glish function naming policy of the previous section; both are designed to present the end user with only lower case commands to type, but note that underscores are prohibited in file names.)

Use the standard extensions (.c, .cc, .h, .f, .g).

Format for Dates

Programmers (and code reviewers) must enter dates when documenting code. These dates indicate, for example, when code has been reviewed, and when a list of ``to do'' tasks was last updated.^6.13AIPS++ uses a single mandatory format for expressing dates. It has the virtue of being unambiguous, it is comprehensible to readers around the world, and it is also used by the project's version control system RCS. This format is yyyy/mm/dd. An example is 1995/02/27.

Next: Coding Up: Standards and Guidelines Previous: Code Organization Contents Index