User Tools

Site Tools


commenting_20library_20code

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

commenting_20library_20code [2018/03/31 13:19]
127.0.0.1 external edit
commenting_20library_20code [2018/04/15 18:14] (current)
tbest3112 Added syntax highlighting
Line 3: Line 3:
 //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.\\ \\  //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 ==== ==== 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:​\\ \\ +\\  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 bb4w>
         REM <Library name> <​version>​ <​date>​         REM <Library name> <​version>​ <​date>​
         REM (C) <​Author>,​ <​year>​ (<email address>​)         REM (C) <​Author>,​ <​year>​ (<email address>​)
         REM <Link to your web site>         REM <Link to your web site>
         REM <Purpose of library>         REM <Purpose of library>
-        REM <​Distribution and usage conditions>​+        REM <​Distribution and usage conditions> </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.\\ \\  \\  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 ==== ==== Commenting routine usage information ====
Line 17: Line 17:
   * The function'​s input parameters   * The function'​s input parameters
   * The meaning of any return values   * The meaning of any return values
-\\  For routines used internally by the library the following comment is sufficient:​\\ \\  +\\  For routines used internally by the library the following comment is sufficient:​\\ \\ <code bb4w> 
-        REM For internal use only+        REM For internal use only </​code>​
 \\  \\ 
 ==== Commenting the library 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. \\  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.
commenting_20library_20code.txt · Last modified: 2018/04/15 18:14 by tbest3112