Code Documentation[LINK]

In addition to a uniform programming style, proper code documentation will enhance the understandability and maintainability of EnergyPlus. Code documentation includes the comments within the source code as well as written documents. Neither documentation type is intended to be a program tutorial or textbook in building energy analysis physics. Code developers should assume that readers of the documentation will be familiar with standard engineering terminology and have a basic understanding of the processes involved. In cases where extremely complex algorithms are involved, developers should provide as many detailed comments as possible but refer the reader to an appropriate text or article. It should be noted that program code will not be considered complete until the proper documentation for that section of the program is complete.

Source Code Comments[LINK]

Source code comments include the information sections contained in the code template in the previous section as well as any additional in-line comments. Again, the object is not to document obvious lines of code but to assist the reader in understanding the code. For example, an in-line comment for an assignment statement probably should not repeat the equation being described because in most cases it will be obvious what is being calculated due to the use of longer variable names. If there are several similarly named variables in an equation, it may be necessary to explain the differences between them. In most cases, if the equation is unique to a particular method, then a citation to one of the references should be given (e.g., Conduction of Heat in Solids, Carslaw and Jaeger. 1946. p. 123, Equation 2.1.5). If a particular algorithm with distinct steps or milestones is used, the addition of such information to the code using in-line comments can be very effective. Do-loops and If-then constructs should have comments that enhance the description of the loop or decision being made.

Engineering Documentation[LINK]

The written documentation for each module must include user documentation, interface developer documentation (if appropriate), and engineering or technical documentation. The user documentation must incorporate basic facts about how the model is used in the program and some information on the limits of its application within the program. This information should be tailored to someone who will use the program as a “black box”. These users are not concerned with the calculation procedures used by EnergyPlus but are concerned with how to get reasonable results out of the program. The interface developer documentation must provide a detailed description of what input is necessary for the model. Generally, this can be in the form of comments in the Data Dictionary (IDD) file. The module developer must ensure that important information such as input units are part of this documentation section. Finally, the technical documentation should include more detailed information on the processes being programmed. This information must be similar to the documentation found in the program code and be written with other code developers in mind. As with the in-source documentation, avoid lengthy discussion of minute details that are already discussed in reference documents. However, information important to the calculation procedure or any numerical techniques that are used must be highlighted.