Jack Born On Marketing, Online Business, and PHP Code

When I was teaching myself PHP many, many years ago I thought that commenting my code was a complete waste of time. I was writing the code for my own use and so it wasn’t important to me that someone else be able to follow my logic very easily.

Fast forward through the years and today I find commenting my code to be one of the most important ways to save myself time. With all the projects I’m constantly juggling, it’s critical for me to comment my code so that I can come back days, weeks, and sometimes months later and pick up where I left off without much effort.

Every programmer that comments their code has their own way of doing it, but here’s mine.

First, I don’t use // to comment my code unless it’s a very short comment. I tend to use these at the end of my control loops to keep things straight. I won’t go into this here, because I wrote an entire post about managing control loops in PHP.

So I favor the comments that start with /* and end with */. Some of my code I do sell to other php programmers and invariably someone will open up my code in WordPad or something else that likes to wrap long lines of text. I got lots of requests for help back in the days when I’d add comments to the end of some code with // and make what should be a short line of code longer than necessary. When the text editor wrapped the line, the code broke.

For example, imagine a configuration file with the following line:

$username = '';//This is the spot where you put the username for your database. You need to make sure that you have assigned the user to the database before proceeding.

See that line wrap? This can be solved by starting a comment with /* and ending with */.

On a side note, any text editor that wraps long lines of text is not to be used to edit PHP, but if the person using your code is new to PHP, they don’t know this. You’re better off writing your code for the greenest of newbies.

The other thing I do with my comments is that I will break my length code into sections and put ample comments at the start of each one. So, if my code were a form mailer, there’s a section for checking the input for validity, a section for setting the database and mailer classes, a section for the logic, a section for sending the emails, and a section for fetching templates and sending output. I would divide these up like so:


/***************************
Now we check the input and
clean the variables before adding
them to the database
***************************/
code
code
code
code
/**************************/

See how I could come back months later and know exactly what each section does?

My comments tell me where a section starts and where a section ends.

Notice that I use my own line breaks to keep the comments over on the left hand side of the page. I do this so that long comments don’t force me to scroll to the right to see what my notes are.

I also find that the way I open and close comments like this makes it very quick and easy to type out a comment.

Try it out and you might like it. If you juggle lots of projects, you’ll thank me later for saving you hours of frustration.

This entry was posted on Sunday, June 12th, 2005 at 11:23 am and is filed under Programming . You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.