commenting_20library_20code
Differences
This shows you the differences between two versions of the page.
| Next revision | Previous revision | ||
| commenting_20library_20code [2018/03/31 13:19] – external edit 127.0.0.1 | commenting_20library_20code [2024/01/05 00:22] (current) – external edit 127.0.0.1 | ||
|---|---|---|---|
| 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 ' | //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 ' | ||
| ==== 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: |
| REM <Library name> < | REM <Library name> < | ||
| REM (C) < | REM (C) < | ||
| REM <Link to your web site> | REM <Link to your web site> | ||
| REM <Purpose of library> | REM <Purpose of library> | ||
| - | REM < | + | REM < |
| \\ 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' | * The function' | ||
| * 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: |
| - | REM For internal use only | + | REM For internal use only </ |
| \\ | \\ | ||
| ==== 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.1522502349.txt.gz · Last modified: 2024/01/05 00:18 (external edit)