27.th April and 4.th May 2000, Simastuen

Meeting 4^th May

Executive Summary

We discussed the documentation of the program

Detailed description

Jørn Amundsen gave a brief introduction to the Linux cluster available at ITEA. This included the hardware configuration and software and development tools featured on this computer.

We discussed the structuring of the source code in order to create more easily readable documentation. There were two different approaches to this structuring.

Diffpack style; write full documentation for each method in each header file using the Diffpack conventions. This makes for easy parsing by standard Diffpack tools such as dpman(1). A drawback is, however, that the documentation for each method occurs in different places, which may render the maintenance of the code somewhat more laborious.
Rational Rose style; short comments, if any, about the method/function in the header file. Detailed descriptions of the method where it is implemented (in the .cpp-file). The advantage of this approach is that the documentation, however detailed, occurs in one place and may be more easily updated when implementational details change. There is unfortunately no simple tool which will display the documentation like dpman(1), but we can create a parser (for instance in Perl) if we come up with good markers for logic within the comments/documentation.

There were arguments in favor of both approaches, but the general impression was that the latter would be used, especially if the aforementioned parser is made. We definitely want a consistent way of documenting our work, so consideration should go into the final decision.

Next meeting: Thursday 11^th May 2000, Simastuen, 14:15

Please, send any comments by email to: Bård Skaflestad <bardsk@math.ntnu.no>

Last modified: 2000-05-10 16:05+0100