Specifications

Commenting Your Code
All programs should be commented to a sensible level. You might ask what level of comment-
ing is sensible. Generally you should consider adding a comment to each of the following
items:
• Files, whether complete scripts or include files. Each file should have a comment stating
what this file is, what it’s for, who wrote it, and when it was updated.
• Functions. Function comments should specify what the function does, what input it
expects, and what it returns.
• Classes. Comments should describe the purpose of the class. Class methods should have
the same type and level of comments as any other function.
• Chunks of code within a script or function. I often find it useful to write a script by
beginning with a set of pseudocode style comments and then filling in the code for each
section. So an initial script might resemble this:
<?
// validate input data
// send to database
// report results
?>
This is quite handy because after you’ve filled in all the sections with function calls or
whatever, your code is already commented.
• Complex code or hacks. When it takes you all day to do something, or you have to do it
in a weird way, write a comment explaining why you did it that way. This way, when
you next look at the code, you won’t be scratching your head and thinking, “What on
earth was that supposed to do?”
Another general guideline to follow is that you should comment as you go. You might think
you will come back and comment your code when you are finished with a project. I guarantee
you this will not happen, unless you have far less punishing development timetables and more
self-discipline than we do.
Indenting
As in any programming language, you should indent your code in a sensible and consistent
fashion. It’s like laying out a resumé or business letter. Indenting makes your code easier to
read and faster to understand.
In general, any program block that belongs inside a control structure should be indented from
the surrounding code. The degree of indenting should be noticeable (that is, more than one
space) but not excessive. I generally think the use of tabs should be avoided. Although easy to
Using PHP and MySQL for Large Projects
C
HAPTER 22
22
USING PHP AND
MYSQL FOR
LARGE
PROJECTS
465
28 7842 CH22 3/6/01 3:37 PM Page 465