We can’t stress it enough—even though while programming you may think it’s the
dumbest thing to do—commenting is substantial when producing high-quality code.
When solving complicated problems, seldom do two people think the same way.What
may be totally obvious to one is obscure to the other. Comments are very helpful in
these situations, and they should be added to your code wherever possible.
There are two main kinds of comments: header comments (such as comments in file
headers, module headers, or function headers) and inline comments. Header comments
should be used for purposes of introduction; to inform the reader about generic things
in a file; or about the next, larger piece of code. Inline comments should be used
within functions, embedded into the code, to explain what a certain line or block of
code is actually doing.
The following sections should give you an idea of the look of these comments
and the information that they should contain.These days, such comments are usually
produced by Rapid Application Development (RAD) tools or other authoring aids,
but since no similar systems are available for PHP at the time of this writing, the
comments should be handcrafted, in spite of the additional workload.
In the following sections, the comment types are discussed in order of abstraction,
from most abstract to most concrete.
Keeping Comments Up to Date
File Header Comments
On UNIX systems, the following grep command extracts such block comments from the source:
grep ‘^[\\\/ ]*\*’ source.php3
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.
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 every-
thing 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.
Ask yourself these questions when commenting code:
What are you doing?
Why are you doing it?
Why are you doing it this way?
Why are you doing it at this point?
How does this code affect the other code?
What does this code require?
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 com-
ments by placing a link to the documentation there as well.
Choosing Speaking Names
As mentioned earlier, choosing appropriate names for functions and variables is an
essential issue in programming. Generally, when selecting a name for a variable, it’s
important to first determine whether the variable is local or global. If the variable is
only visible in the local scope of a function, choose a short, precise name that states
the content or meaning of this variable.
$counter
$next_index
$nrOptions
$cookieName
Remember not to mix naming schemes! Either use all lowercase variable names, separating
words with an underscore, or use capital letters to separate the words.You can also use
both capital letters and underscores to separate words, but never use capital letters for
one variable and underscores for another.This leads to mistakes and exhibits poor
style. After you’ve found your own style, keep it consistent throughout the project.
Each global variable should have a prefix that identifies the module to which it
belongs.This scheme helps to assign globals to their modules, as well as to avoid con-
flicts when there are two variables of the same name from different modules in the
global scope.
MY_GLOBAL
As this example shows, global variable names tend to be longer than local variable
names.This is due not only to the module prefix but also to clarification practices.
When the definition and initialization point of a variable are unknown because
they’re hidden in a module to which you don’t have access, it’s very important to
reflect the variable’s meaning and contents in its name.There’s a practical limit to this,
of course—nobody would want to remember names of 40+ characters—but this is
more a limit of common sense.
