|
|
|
|
| Tutorial |
Chapter 1 Development Concepts
Listing 1.5 Continued
// and includes error checking and reporting.
//
// Functions:
//
// int file_open(string $file_name)
// bool file_close(int $file_handle)
// int file_read(int $file_handle, $nr_bytes)
//
// Remarks:
//
// - provides no seek function
// - does not allow write access
//
///////////////////////////////////////////////////////////////////////////////
These headers might include the following items, in order:
1. Short module description.
2. Detailed module description.
3. Function prototype list.
4. Remarks/notes.
Again, multiline comments work as well.
Function Header Comments
Function headers should describe the syntax, purpose, and necessary caller information
in enough detail for each function (see Listing 1.6).These kind of comments are secondary
in importance only to inline comments. Function header comments serve the
purpose of quickly informing the programmer about the requirements and specialties
of each function during development and extension of a module, mainly needed by
“foreign” developers who didn’t create the functions originally.A lack of function
header comments usually requires a developer to dive into the code itself to find out
the required information, which often results in mistakes because not all hidden traps
(sometimes very well hidden) are seen.
Listing 1.6 Typical function header comment.
///////////////////////////////////////////////////////////////////////////////
//
// int irc_get_channel_by_name(string $name)
//
///////////////////////////////////////////////////////////////////////////////
//
// Searches a channel by its name in the internal channel table and returns
// its handle.
//
|
|
|
|
|
|
| Link Partners: Asia florist, Flowers to India, Hong kong flowers, Site submit, Cheap web hosting, China florist, Japan florist |
|
