In this two-part series, we're taking a look at building a case for code comments. In the first article, we covered the server-side by taking a look at PHP. Specifically, we reviewed PHPDoc conventions and how to use them to document templates, functions, and lines and blocks.
In this article, we're going to take a look at client-side languages. Specifically, we're going to look at HTML, CSS, and JavaScript.
Although there aren't necessarily documentation utilities such as phpDocumentor for all of these languages, there are still strategies that we can employ to make maintaining our projects (or helping others contribute to our projects) a bit easier.
Client-Side Languages
When it comes to working with WordPress, themes and plugins will vary in the type of files that they include. Themes will usually consist of HTML and CSS and probably some JavaScript, whereas plugins may only consist of PHP.
In the first article, we looked at what WordPress requires in order to register template files with the API as well as what plugins require. Before reading ahead, I recommend reviewing that article first as it covers the required information whereas this particular article is only going to cover recommendation for what we can do to improve our comments.
Markup
Most web developers are aware of how to write comments within the context of HTML. Simply, it's a matter of prefixing the code - be it a single line or block - with <!-- and suffixing the code with -->. When it comes to writing markup, it's not terribly common to see comments beyond conditionals that you may find in the head element of the document.
There are techniques that we can use to make our code more maintainable. This is especially useful when working with systems like WordPress because certain elements will be spread across multiple files.
For example, assuming that you're building a theme, you're likely going to be opening your body element and a container element in the header.php template and then terminating the elements in the footer.php template.
This is a bit of a simplified example as it's relatively common, but the principle stays true through the other files.
With that said, there's a simple strategy that we can use for commenting our code:
HTML elements will generally be in one of four forms:
- The element will not include an ID or a class
- The element will only include an ID
- The element will only include a class
- The element will include both an ID and a class
For each of these permutations, I follow the following conventions:
No ID or Class
<form method="post" action="options.php"> <?php /* Snipped for brevity */ submit_button(); ?> </form>
Above, there's a code snippet for a form that's used to save options to the WordPress database form within the Dashboard. In this case, I'll normally leave a comment at the end of the element that indicates the purpose of the form or some other attribute, such as the action attribute.
Given that strategy, the above example may look something like this:
<form method="post" action="options.php"> <?php /* Snipped for brevity */ submit_button(); ?> </form><!-- /options serialization -->
Or:
<form method="post" action="options.php"> <?php /* Snipped for brevity */ submit_button(); ?> </form><!-- /options.php -->
The convention that I opt to use is to use a backslash - in normal HTML fashion - followed by the purpose of description of the element to let me know that I'm terminating the element.
Though this may not be especially useful with a single isolated element, I've found it to be helpful with nested elements as well as when an element - like a container - is split across files.
Only an ID
In the case that the element has an ID, I use the following comment:
<div id="wrapper"> <!-- nested elements removed --> </div><!-- /#wrapper -->
Just as above, I use a backslash followed by a '#' which represents an ID in CSS followed by the name of value of the ID attribute. This let's me know that I'm terminating an element with the given ID.
Again, this is most useful when an element exists across files, but it's also helpful when you need to do a global find in template files or in CSS files.
Only a Class
When an element includes only a class (or a set of classes), I follow a similar strategy as above - I use a backslash, the CSS indicator for a class, and then the class (or the first class) on the element:
<div class="container"> <!-- nested elements removed --> </div><!-- /.container -->
Simple enough.
Both an ID and Class
But what happens when the element includes both an ID and a class? Since ID's are unique and classnames are not, I always default to using the ID of the element when terminating the comment:
<div id="post-meta" class="post-meta-data meta-link pull-right"> <!-- PHP snipped for brevity --> </div><!-- /#post-meta -->
Makes sense, right? And the point still remains: This makes it easy to know which element I'm ending and makes it easy to find it throughout the rest of the project files.
JavaScript
JavaScript is similar to PHP in that it supports higher-order features such as functions (and prototypes if you're writing vanilla JavaScript). Because of that, having a convention by which we document our functions is useful.
Here's the thing: WordPress includes jQuery by default so it's common for most WordPress-specific JavaScript to be written using a combination of jQuery-based JavaScript and vanilla-based features like functions.
The following strategies have proved useful in writing JavaScript in WordPress:
Describe the Purpose
First, I try to name the file based on the purpose that it serves (such as navigation.js or theme.js or admin.js).
Secondly, I'll also provide a short description at the top of each file using PHPDoc conventions for describing the file and how long it's been part of the project:
/** * admin.options.js * * Manages the event handlers for several elements on the Dashboard options page. * * @since 1.0 * @version 3.2 */
Documenting Functions
For functions, I follow a similar convention as above in that I'll provide a short description of the function, describe what it accepts, and what it returns, as well as how long it's been in project and the current version of the file:
/** * Helper function that's fired when the user clicks 'Done' or hits 'Enter' * when working to save their social icons. * * @param $ A reference to the jQuery function * @param evt The source event of this handler * @returns Whether or not the user hit enter or cancel to save their options. * @since 1.0 * @version 1.2 */
On Lines and Blocks
This is really nothing more than standard code comments which most developers often use. There's the single line variation, the multiline variation, and the purpose they serve: That is, simply to describe what's about to happen in the code following the comment.
/*
* If we're looking at the RSS feed icon, disable the input
* and link the user to the Global options for where to set it.
*/
if ( '' !== sRssUrl ) {
$('#social-icon-url')
.val(sRssUrl)
.attr('disabled', 'disabled');
} else {
$('#social-icon-url').removeAttr('disabled');
} // end if
There's very little to add to this that I've not covered in the first article, but I did want to mention it here for review and to be complete.
Documentation Tools?
Though there's no official JavaScript documenting tool, jsDoc has become one of the most common utilities for documenting JavaScript code.
Stylesheets
Commenting CSS files is decidedly much easier than working with PHP or with markup because there's really only a single way to write styles.
That is, you define styles for an element using an ID or a class:
#no-comments {
font-size: 24px;
line-height: 36px;
font-weight: bold;
color: #444;
}
Or:
.home .sticky:before {
display: inline-block;
background: transparent url(images/sticky.png) no-repeat;
width: 58px;
height: 45px;
content: "";
position: absolute;
top: 26px;
left: -9px;
}
Generally speaking, I don't think you need to comment styles, but if you find yourself in a situation where the terminating bracket is off the screen, then it may be useful to end the style with a comment like this:
#no-comments {
font-size: 24px;
line-height: 36px;
font-weight: bold;
color: #444;
} /* #no-comments */
Or:
.home .sticky:before {
display: inline-block;
background: transparent url(images/sticky.png) no-repeat;
width: 58px;
height: 45px;
content: "";
position: absolute;
top: 26px;
left: -9px;
} /* .home .sticky:before */
What About Preprocessors?
Right now, using languages such as LESS and Sass and their respective preprocessors is becoming more and more popular in web development. One of the most common features of these two languages is that they support nested rules.
In this case, I think there's a much stronger case for using comments. For example:
#header {
#slideshow {
#image-list {
list-style: none;
float: left;
margin: 0;
width: 100%;
} // #image-list
} // #slideshow
} // #header
This way, you know what element you're terminating regardless of where the element begins in the IDE.
Conclusion
Throughout this series, I've outlined why I believe code comments should be something that all developers should include in their code. In this article, I've discussed my strategies for how I comment my markup, my JavaScript, and my styles.
Though I'm not saying my way is the only way to write comments - it's but one way - I do believe that including comments goes a long way in making a project more maintainable for yourself and your peers, and I think that including them in your work is something that each developer should aim for.
Hopefully this series has provided a case for just that. Regardless, I'd love to hear your thoughts and suggestions in the comments.
Comments