Getting Started Documentation Glish Learn More Programming Contact Us
Version 1.9 Build 1367
News FAQ
Search Home

next up previous contents
Next: Defect handling Up: Software engineering practices in AIPS++ Previous: Releases

Subsections

Code development

The following practices apply to the code development cycle.

Requirements

Scientific requirements for any given area of development are established in consultation with external users competent in the relevant area, in broad consultation within the consortium. The requirements are expected to be specific and well-defined, and to include their perceived scientific priority. Requirements may be sub-divided by instrument, as appropriate.

Design

The following level of design control and review is adopted:

1.
Initial design: A design is expected to be drafted for each component under development for any given target. This should constitute the .h files, explanatory notes and may be accompanied by a thin prototype where appropriate.

2.
Design review: A review of the initial component design will be conducted by the developer responsible for the module or area of development for consistency with the overall module design. This may include a higher level review for consistency with the project design or integration standards, as noted below.

3.
Documentation: All designs need to be documented in the project documentation on acceptance.

4.
Integration: All module or component designs need to be consistent with higher-level integration policies, and the overall design established for the project. This is arbitrated at higher levels of coordination responsibility assigned within the project, including project management.

Implementation

During implementation, the following policies are applicable:

1.
Coding practices: Coding conventions, standards and practices are set by the technical leader, on advice from the QAG.

2.
Project compiler: The project has a policy of a single project compiler in order to ensure maximum build stability so that applications can be delivered on time to end-users. All developers are expected to use the project compiler for development, and all code checked-in needs to compile with this designated compiler. The project compiler is set periodically subject to the following criteria:

3.
Secondary compilers: Secondary compilers may be designated by the technical leader if resources are available for their support. Code only needs to be checked against the project compiler, however, as noted above. A designated group will be responsible for ensuring a clean build on each secondary system, and are expected to resolve the overwhelming majority of any compiler or syntax support issues on these systems. Other developers may however be consulted for assistance or advice if changes need to be made to their code, particularly if these changes are subtle. In the event of syntax support conflicts, the C++ standard takes precedence unless not supported by the project compiler in the specific instance. Compiler defects are expected to be flagged with #ifdef statements for ease of later removal. Compiler defects need to be recorded for reference by other developers, and submitted to the vendor for correction.

4.
Code development tools: The project tests code development tools, such as memory leak detectors, periodically. If they work with the AIPS++system, and are useful, they are added to the list of recommended tools for use in debugging or testing. Consortium sites are not required to purchase these tools however, although passing tests with some of these tools may be part of the code review standards recommended by the QAG.

5.
Code re-use: Developers are expected to re-use AIPS++ library code wherever possible, without duplicating core library capabilities.

Code check-in and check-out

All code is under revision control on each master. Check-in and check-out proceed by the following guidelines:

Check-out: Any file which is being actively modified by a developer, as opposed to testing or evaluation, needs to be checked-out with locking enabled. Files should be locked for the minimum period of time consistent with completing the work required.

Check-in: Files checked back into the system need to be tested for compiler and run-time errors, and should form part of a self-consistent group of files, which will not break the build. This includes making changes in all other parts of the system which depend on the code which has been modified, for all except contributed code. In rare circumstances, check-in's which require multiple days and may break the system will be scheduled after consultation with the project. Code which breaks the daily build inconveniences other developers and delays applications delivery.

RCS logs: Descriptive RCS entries are required for each file on check-in. The general guidelines for RCS entries are: i) Descriptive, complete and readable. Useful to another developer; ii) Reference defect numbers which are being fixed, but provide a one-line defect title with the defect ID; and iii) Please avoid: i) "Fix typo"; ii) "Fix error"; iii) "Fix bug", or; iv) "Null Ctrl-D".

Changelog entries: The changelog aims to document changes to the code distribution at a level higher than file-based RCS entries, as currently added by ai. The changelog is intended to summarize a sequence of related RCS changes in an overarching description, accessible to both scientific end-users and other AIPS++ developers. The overall goals of the changelog in this context are: i) flag changes in AIPS++ which are of interest to end-users of AIPS++; or ii) highlight changes which are of relevance to other AIPS++ developers using the affected code. Changes which meet any of the following criteria require an entry: i) important changes in design; ii) changes in the user interface; iii) addition of new features or adoption of new algorithms; iv) correction of major errors found in the code; v) major implementation changes, including significant code re-organization. These principles are taken to cover new code and documentation added to the system, code removed from the system, modification of existing code, and changes required to correct defects. Changes which do not requires changelog entries include: i) Modest changes in implementation, not visible or relevant to other developers or end-users; ii) Editing of documentation; iii) Defect correction with limited impact outside of the affected code or module; iv) Minor design or user interface changes.

Testing

The AIPS++project requires unit test programs for all code, which are exercised automatically after specified builds, and the results recorded. These are used to track and ensure build correctness. Integration testing is regarded as equally important, and usually takes the form of Glish scripts, to ensure the inter-operability of higher-level modules. The following forms of testing are encouraged, in order:

For a specific testing
Check list:

Test case development
A good test case has the following attributes.

Test case Template

Documentation

Code documentation policies are established and publicized by the QAG. The utility cxx2html is used at present to extract C++ documentation tags and convert them to html. The code documentation policies include style guides to be used in document preparation.

Code acceptance

Code is initially developed in the trial area, and is migrated to aips on acceptance. The code review process is coordinated by the QAG. Code review is an important process, and time will be specifically scheduled for this purpose in the planning process.

next up previous contents
Next: Defect handling Up: Software engineering practices in AIPS++ Previous: Releases   Contents
Please send questions or comments about AIPS++ to aips2-request@nrao.edu.
Copyright © 1995-2000 Associated Universities Inc., Washington, D.C.
Return to AIPS++ Home Page
2006-03-28