BBC BASIC Programmers' Reference

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.

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:

      REM <Library name> <version> <date>
      REM (C) <Author>, <year> (<email address>)
      REM <Link to your web site>
      REM <Purpose of library>
      REM <Distribution and usage conditions>

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.

Consider adding a block of comments in the source code before each function and procedure is DEFined 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:

      REM For internal use only

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.