Commenting+library+code

//by Jon Ripley, July 2006//

All programs and libraries should be supplied with adequate documentation to enable yourself and other programmers to use the library in their programs. Comments form an important part of library documentation and should not be overlooked. Time taken during development to adequately comment a library can save time in the future when the library is used or updated.

Although adding comments to programs will necessarily increase the library size this space is reduced to zero, or less, if the program is compiled with the 'Remove REMs' option enabled.

The initial comment block
A library should begin with an initial comment block describing at least the library name, version, author, a web site link, your email address and usage conditions. The comments give programmers valuable meta information about your library and enables them to ensure they are using the latest version and can contact you with any comments, queries or suggestions.

Suggested comment block to begin libraries:

code format="bb4w" REM  REM (C) , REM  REM  REM  code

Replace the text between each chevron pair with relevant information about your library.

The layout and content of the initial comment block is entirely at your discretion.

Commenting routine usage information
Consider adding a block of comments in the source code before each function and procedure is **DEF**ined to document each routine. This aids programmers using the library and can save time by removing the need to consult the documentation.

Provide concise relevant usage information. Suitable information includes:


 * The name of the routine
 * What the routine does
 * The function's input parameters
 * The meaning of any return values

For routines used internally by the library the following comment is sufficient:

code format="bb4w" REM For internal use only code

Commenting the library code
Comments inside library routines are as important as comments in all other code and will help yourself and other users of your library understand how the functions work. Commented code is valuable when the library needs to be updated, either to add new functionality or to fix bugs in the code.

No matter how well you understand how the code works at the time you write it, without adequate comments the same code may become unmaintainable in a few months time. Comments are essential for all programmers who work with code.