|
|
|
|
| Tutorial |
///////////////////////////////////////////////////////////////////////////////
//
// Parameter:
// $name - name of channel to search for
//
///////////////////////////////////////////////////////////////////////////////
//
// Return value:
// Channel handle (numeric), 0 on error
//
///////////////////////////////////////////////////////////////////////////////
//
// Global references:
// $irc_channel_array
//
///////////////////////////////////////////////////////////////////////////////
A function header comment should contain a collection of the following items,
in order:
1. Function prototype.
2. Detailed function description.
3. Remarks/notes.
4. Parameter description.
5. Return value description.
6. Global references.
7. Author and date of last change.
Inline Comments
Inline comments are placed directly into the code and should explain all questions
directly where they arise. Note that while you’re programming, it’s natural that everything
is perfectly clear to you as you type it.This is usually the cause for too few
comments.When you reopen this file at a later point, maybe even after a year, you’ll
have forgotten about all the structures you used and why you used them.We’ve
encountered this problem too often, in our own code and that of other people.The
rule for inline comments is that you can hardly use too many.The only exception to
this rule is when comments are overused to the point that they obscure the code
they’re meant to describe.Also, you should be careful not to comment obvious things.
See Listing 1.7 for a few examples.
|
|
|
|
|
|
| Link Partners: Asia florist, Flowers to India, Hong kong flowers, Site submit, Cheap web hosting, China florist, Japan florist |
|
