Getting Started

Documentation

Glish

Learn More

Programming

Contact Us

Version 1.9 Build 1556

News	FAQ
Search	Home

General

There are eight documents, in addition to this one, which are essential to the code preparation and review process. Both programmer and reviewer should study them carefully, and base their work upon them.

• code/install/codedevl/template-class-h: how to construct a class header file.
• code/aips/implement/Lattices/Slicer.h: good example of a class header.
• code/install/codedevl/template-module-h: how to construct a module headers file.
• code/aips/implement/Tables.h: good example of a module header.
• code/install/codedevl/template-global-functions-h: how to construct a header file for global functions.
• code/aips/implement/Arrays/ArrayIO.h: good example of a global function header file.
• code/doc/notes/167.latex: Standards and Guidelines Checklist.
• http://www.cv.nrao.edu/aips++/docs/html/cxx2html.html An online guide to the documentation extractor, with good descriptions of the markup tags to be used in creating header files.

There are three main goals for the code review, all of which are equally important:

• Guarantee that the fundamental design of the class, as exposed in the public interface, is sensible and reasonably complete. We are more concerned about overall design than implementation details, because we assume that the programmer is competent; that the implementation may be too complicated to analyze in a reasonable amount of time; and that test programs and early usage will indicate errors and gross inefficiencies. The public interface, though, is everyone's concern, it is a good indicator of overall design, and it is painful to change once a class has been checked in.
• Make sure that the class header file is a sufficient guide to the class for client programmers. This is a very high standard, and demands a great deal of work from the programmer and the reviewer. ``Sufficient'' means that a programmer, previously unacquainted with the class, can read the header file and quickly reach a point where he or she can write code that uses the class. This standard of explanation is often met by well-written programming books, and is rarely met by programmers in their own internal documentation. It is, nonetheless, the standard for all AIPS++ source code.
• Use the test program(s) to make sure that memory leaks are discovered and removed. See that code coverage is about 90% complete².

A great deal can be learned from reading through a class, and running test and demo programs. But no review is complete until other programmers use the new code. For this reason, we have a package called trial.³This package is automatically distributed by the AIPS++ code distribution system. If you ask the code cop to install your code in the trial directory, it will be available for everyone to examine and use. (All of these possible users will understand that trial code is subject to change with little or no notice.)