|
|
|
|
| Tutorial |
Chapter 1 Development Concepts
Listing 1.7 Bad inline comments.
function calculate_next_index ( $base_index )
{
$base_index = $base_index + 1; // increase $base_index by one
//
//
// Table of contents
//
// 1. Introduction
// 2. About the authors
[LOTS of lines cut out]
//
//
$new_index = $base_index * COMPLICATED_NUMBER / 3.14 + sin($base_index);
}
$base_index is increased by 1 in the first line of code—is that something to comment?
We doubt it. Everyone can see that $base_index is being incremented, but why is it
incremented, and why is it incremented by 1 exactly? A better comment would be
something like Jump to the next ordinal index we want to point to; it’s
exactly one element away.
The same kind of problem is introduced with the second comment, but with a different
cause.The programmer has pasted the complete reference for the algorithm into
the code, including lots of inappropriate junk. Of course, it’s good to describe in detail
what you’re doing, but you have to filter what’s really important and what isn’t.
Ask yourself these questions when commenting code:
n What are you doing?
n Why are you doing it?
n Why are you doing it this way?
n Why are you doing it at this point?
n How does this code affect the other code?
n What does this code require?
n Are there any drawbacks to your method?
For example, when you’re parsing strings, document the format of the input strings,
the tolerances of your parser (its reactions to errors and mistakes in the input), and its
output. If all this information is too heavy to include it directly into your code, keep
at least a pointer to external documentation where the reader can inform himself
about all aspects of the parser.Also, remember to update your function header comments
by placing a link to the documentation there as well.
|
|
|
|
|
|
| Link Partners: Asia florist, Flowers to India, Hong kong flowers, Site submit, Cheap web hosting, China florist, Japan florist |
|
