Options in Source Code Documentation

摘要

Customers using system dynamics models for multipurpose applications require varying degrees of documentation of a model’s source code and design. A broad range of factors can influence the customers’ documentation requirements. Because the model developer plays an important role in determining a model’s functional requirements and has often been exposed to a range of model applications and documentation requirements, the developer is in an excellent position to understand and advise the customer on what level and form of source code documentation may be appropriate for a specific application. This paper will discuss the range of documentation alternatives considered by Raytheon Company C3I Systems, Project Performance Corporation, and U.S. Government customers in documenting source code for various system dynamics models. The paper also discusses the factors that were considered as potentially influencing the customer’s documentation requirements. The most expeditious documentation is often developed automatically when using commercially available off-the-shelf system dynamics software. More rigorous documentation can also be developed manually, either during or after development of the model. In addition, rules-of-thumb and informal professional practice standards exist for documenting source code.Source code documentation serves two primary purposes. First, it is a quality assurance tool that helps to minimize the number of defects or bugs in the source code. Second, it can lower the life-cycle cost of the model by reducing the learning curve and costs associated with evaluating and modifying the source code. These two purposes are the dimensions of the cost-risk decision that model owners face when making documentation decisions. Factors considered in the decision include the model purpose, the expected frequency and duration of model usage, the experience and knowledge of model users, the potential costs associated with model misuse or failure, and the direct costs of preparing and maintaining documentation.