Version 1.9 Build 1556

News	FAQ
Search	Home

Next: Documentation and Naming Up: NOTE 167 AIPS++ Programming: STANDARDS AND GUIDELINES Previous: Introduction

Subsections

Code Organization

Classes

Every class will have a header file,¹ an implementation file,² a test program ³ and (optionally) a demo program. Very closely related classes⁴may sometimes be combined into single header and implementation files.⁵

All files shall follow the latest template file as a guide for the standard layout.

It is sometimes advisable to separate the implementation into different files. Examples are to separate templated and non-templated methods, and when a sub-set of the methods is often used. Such implementation files have in general names like name2.cc etc. See code/aips/implement/Arrays/Array2.cc for an example.

The test program(s) shall exercise every member function, every exception, and cover at least 90% of the lines of code in the implementation file.⁶

Include files

Whenever possible the header files should use forward declarations⁷ in stead of include files. Include files should be reserved for the implementation files.

Data Types

Only the standard AIPS++ data types ⁸ shall be used, coded in the AIPS++ way.

Modules

Closely related classes should be organized into a module - which requires an appropriately named, separate directory.⁹ Modules are assigned by the AIPS++ system manager. The module will have a ``module header file'' - whose primary purpose is to simplify things for the application programmer by providing sufficient help information for the general use of the classes in the module. Whenever possible, application programmers should not be required to learn the intricacies of a complicated module, nor to understand specific implementation classes within the module. In these cases they should only have to include a single header file into their application program. In cases where the role of the module is more a conglomerate of related, but independent, classes, individual header files should be used.¹⁰

The module header file ¹¹ will live in the module's parent directory: code/aips/implement/Tables.h, for example, is the module header file for, and describes the classes in code/aips/implement/Tables/.

Global Functions

It is sometimes appropriate to write global functions to act on class objects, rather than creating class member functions. As a general rule, you should do this if there is no class object state preserved from one function call to the next, and all of the information about the class object/s can be obtained from the public interface. However, for reasons of namespace management it is often advised if there exists a strong binding between the class and the global function, to make the global function a static member of the class; or use the namespace keyword. There are two places where global functions may be declared and defined: as part of the .cc and .h files of the class they are most closely associated with, or in their own, separate .cc and .h files. Use these criteria to decide:

1.: If there is a large conceptual distance between the functions and the class, then it is probably best to use separate files.
2.: If there are a large number of related global functions, use separate files.
3.: If the functions are templated, using separate files (at least separate implementation files) will reduce template instantiation dependencies.

Templates

Template instantiations are done explicitly within AIPS++. Make sure templates needed by your code are defined in the package templates file in the _Repository directory. Templates needed only in your test or demo programs should exist in your test/templates file. See the System Manual for details about template management.¹²

File Size (`*`)

Files should rarely - if ever - exceed 2000 lines: a 1000 line maximum will usually apply. Well-designed classes often have short header and, certainly, short implementation files, usually less than 500 lines including documentation.

Function Length (`*`)

Functions should rarely exceed 100 lines in length; shorter, well-focused functions should dominate, and will usually be less than 50 lines.

Next: Documentation and Naming Up: NOTE 167 AIPS++ Programming: STANDARDS AND GUIDELINES Previous: Introduction