How to Comment Code in WordPress Templates

Commenting code is very important to running successful long term websites.

When you come back to code, six months or eighteen months later, you won’t have a clue most of the time how or why it got there. The extra half hour figuring it out (as a minimum) is not worth the two minutes it takes to comment it now.

HTML comments are easy enough.

<!-- this is an html comment -->

When commenting WordPress, I’ve often gotten away with this.

The disadvantage of this method is that the comments show up in every html page for everyone to see your messy code. Too many messy comments may give the Google bot heartburn as well. The less stress you put on their parser, the better for your top-ranked websites. Googlebot’s vulnerability to comment confusion/penalty is probably less of an issue now than it would have been a few years ago (2002 to 2005).

But today I had a batch of PHP which threw errors when enclosed in an HTML comment.

So I had to go looking for a more serious way to comment a WordPress theme template file. WordPress theme template files are PHP so I would have though PHP commenting would work.

When commenting PHP, the following should work

// at the start of a line should make the rest of the line a comment.

But in WordPress templates that doesn’t work.

Alternatively the code for multiline comments CSS is supposed to work in PHP as well

/* here is the comment spanning
multiple lines */

That doesn’t work either in WordPress template files.

So what does work?

This simple syntax:

<?php /*
comment
*/ ?>

You wrap both html and PHP in another PHP tag.

Here is a full scale example:

<?php /*

go wild in this section and write whatever you want and leave whatever messy code you want in here: neither Googlebot or your competitors will see what you are up to. but the notes and functions will be here waiting for you or your programmer when you want to come back and have another stab at what it is you are working on. in this case, archives by year.

    <?php for ($x = date ('Y'); $x >= 2004; $x--) $years[] = '<a href="/weblog/vancouverrealestatenews'.$x.'/">'.$x.'</a>';?>
<?php echo implode (' | ', $years)?>
   
            <?php if (have_posts()) : ?>
                <?php while (have_posts()) : the_post(); ?>

*/ ?>

If you go that that Vancouver real estate news page, you’ll find that none of the above shows up at all.

Commenting code in WordPress templates is simple once you get the hang of it.

Addendum

By force of necessity, I’ve become more proficient at commenting PHP.

To comment part of a section, you have to already be inside PHP tags. So you don’t need to open a new set.

// will get you there as a one line comment if you are in PHP tags and at the end of a line. Line wrap will apply. Just don't hit the return character.

/* Multiple line comments are also possible within PHP comments.
Hit return as many times as you want.
Wrap the comments in the slash-asterisk - asterisk-slash combo */

But all of the above is true if you are trying comment out the html sections of a PHP document. You have to wrap the html in a PHP tag. And if you are trying to build section dividers, you also have to use PHP comment wrappers.