|
|
|
|
| Tutorial |
We believe that this is what code should look like, at least approximately. It shows a
clear structure, is well commented, and is easy to understand.
Adding Comments
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
Remember to create comments before or while working on the module/function they describe; it’s a very
annoying job to rework a file just to add this information afterward. Also, take great care when modifying
functions at a later point—always update your comments appropriately! For example, if you add or
remove global variables, update their usage indication in the comment header as well; the same goes for
changes in parameter ordering, parameter types, and so on.
Use Macros to Speed Up Your Commenting
In your favorite editor, create macros for each comment type and assign them to a hotkey (for example,
Ctrl+Alt+F1 for file headers, Ctrl+Alt+F2 for module headers, and so on). Include variables in these comments
if the editor supports this feature, so that creating an elaborate and informative comment
becomes just a matter of a short Q&A dialogue.
|
|
|
|
|
|
| Link Partners: Asia florist, Flowers to India, Hong kong flowers, Site submit, Cheap web hosting, China florist, Japan florist |
|
