Laserfiche WebLink
CRDSS <br />TASK MEMORANDUM 1.05-11 <br />Study of System Integration Issues <br />Documentation - Documentation of Routines Used in Development <br />1.0 ISSUE <br />Much of the code developed for the CRDSS will be placed in libraries so that the code can be reused <br />in different applications. This code must be thoroughly documented, both internally and externally, <br />so that developers can share routines, and so that the State can maintain the code in the long term. <br />The documentation of routines must use language that can be understood by developers who do not <br />have extensive knowledge about the routines. The following issues must be addressed in order to <br />provide good documentation for routines: <br />What is the format and content of internal documentation (documentation that is in the <br />? <br />source code)? <br />What is the format and content of external documentation (documentation that is external to <br />? <br />the source code)? <br />2.0 DISCUSSION/ANALYSIS <br />The documentation described below will be reviewed by RTi personnel for completeness and <br />accuracy. Each review will be performed by a person who is not the original author of the code. <br />Internal Documentation <br />In general, source code will be split into modules wherever possible. The name of the source code <br />file will be the same as the routine name, including case. For example, a C routine called <br />"GetRatingCurve" will be saved in a file called "GetRatingCurve.c." This allows developers to <br />quickly determine which file contains a routine that needs to be edited. It also eliminates the need to <br />have an index at the top of a source code file indicating what routines are in the file. <br />All code will be fully documented, and C code will be fully prototyped. <br />Documentation for each module will consist of a description of the routine, a history of the routine, <br />and a dictionary of variables. The following template will be used for documentation. Note that <br />not <br />variables are documented on the same line as their declaration. Variables are documented in a <br />header section so that all lead-in documentation is in one place (FORTRAN documentation should <br />be similar): <br />/* <br />** GetRatingCurve - get rating curve for a station <br />** <br />** Notes:(1)This routine gets the rating curve for the <br />**specified station. <br />** <br />1 <br />A275 05.10.94 1.05-11 Malers <br />