Have you looked under the hood of a racing car lately? The bells and whistles inside are a nightmare to figure out. Remember the first time you looked at PHP, CSS, or HTML code? Bet that gave you a few moments of hysteria. When you are releasing your Themes and styles to the public, remember the user may take a peek under the hood and run screaming from the room, too.

What are Comment Codes?

Comments or comment codes are part of code that helps the designer and the user figure out what is what, which section is which, and what is going on within the tangle of codes.

Comments in HTML or PHP pages (outside of the PHP code) look like this:

<!-- comment here about what is going on -->

Comments in CSS files look like this:

/* comment here about a style */

Comments inside of PHP code look like this:

<?php the_excerpt(); // Show excerpt and not full post content ?>

Or like this:

<?php /* This is my special hack.
         It's so special it requires a comment that spans multiple lines! */

my_special_hack();
?>

Tracking Template Files

With the WordPress modular template system, CSS styles can cross files, so tracking down which section a reference is in within the code across template files can be difficult without good commentery. It isn't a requirement, but it is helpful to add a comment to an opening div or class like this:

<div id="sidebar"><!-- sidebar begins -->

Most people familiar with HTML and CSS would recognize that the id is the beginning of the section and a comment might not be needed, but wouldn't it be helpful if at the beginning of every WordPress Loop in every WordPress Theme was the comment:

<!-- WordPress Loop begins here -->

At the end of each div, especially those which cross template files, it would be nice to have an ending comment:

</div> <!-- end content -->

Comments in Style Sheets

Some Themes include CSS inline styles in the header.php, index.php or single.php file, outside of the styles.css theme file.

Typically, if someone is going to modify your carefully constructed and tested theme, there is a presumption that all of the style codes are in the style.css file. If you add any styles to an actual template file, please make a comment about it in the style.css so users know where to find it. There are few things more frustrating than trying to change a style without result, only to find the designer put the overriding style in the header of the actual file.

Just add a short comment like:

/* Styles for the header image are found within the header.php file. */

As important as it is to create the most wonderful and innovative design, it is also important to help the user use your design.

Commenting Out Code

Note: If you are submitting Theme to WordPress Directory, code commenting should not be used.

There are times when you are testing template tags, plugin tags, or different bits of code and you need to prevent them from showing or intiating (being active). To do this, you "hide" them with comment codes. To restore their activation, just remove the comment code.

To hide or deactivate HTML:

<!-- <div class="redblock"><p>This is some HTML in
the redblock class.</p></div> -->

To hide or deactivate CSS styles:

/* .redblock {font-size: 80%; font-style: italic; color: red; } */

To hide or deactivate PHP code in a template file:

<?php // the_content(Continue Reading...); ?>

or

<?php /* the_content(Continue Reading...); */ ?>