|
|
|
|
| Tutorial |
1. Module filename.
2. Short module description (one line).
3. Long module description.
4. Notes about usage, requirements, warnings, and so on.
5. Author’s name and contact information.
6. Creation and last modification date of the module.
7. Copyright notice.
8. License notice.
9. Pointers to change log, home page, distribution file, and so on.
10. Eventually, excerpts from the change log, if needed.
If this sounds like too much information, remember that it’s better to have redundant
information rather than a lack of information. Of course, not all fields are appropriate
under all circumstances; we didn’t include all the fields in the earlier example.
However, you should try to put as much data as you can into your headers—it’s good
style, and the worst that can happen is that some people just won’t read it. Others
might be grateful for it—maybe even you, since neglecting copyright and licensing
information in a commercial project can result in headaches later on, when other
programmers are recycling your code for free.
Module Header Comments
If you have more than one module in a file (for example, when a module only consists
of three functions to abstract functionality from a larger procedure of a bounding
module), you should place an informative header before the very first function.
A module header looks like Listing 1.5.
Listing 1.5 Module header comment.
///////////////////////////////////////////////////////////////////////////////
//
// Submodule for file access from main()
//
///////////////////////////////////////////////////////////////////////////////
//
// This submodule will provide functionality for easy file access,
|
|
|
|
|
|
| Link Partners: Asia florist, Flowers to India, Hong kong flowers, Site submit, Cheap web hosting, China florist, Japan florist |
|
