Advertisement
Creative Coding

A Case for Code Comments: The Client-Side

by

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:

  1. The element will not include an ID or a class
  2. The element will only include an ID
  3. The element will only include a class
  4. 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.


Resources

Related Posts
  • Code
    Theme Development
    Creating a WordPress Theme from Static HTML: Creating an Archive TemplateCreating wordpress theme from html 400
    If you've been working your way through this series, you now have a functioning theme with two page templates. The steps I've demonstrated to this point are: preparing your markup for WordPress converting your HTML to PHP and splitting your file into template files editing the stylesheet and uploading your theme to WordPress adding a loop to your index file adding meta tags, the wp_head hook and the site title and description to your header file adding a navigation menu adding widget areas to the header and sidebar adding widget areas, a colophon and the wp_footer hook to the footer file creating template files for static pages. Read More…
  • Code
    Theme Development
    Creating a WordPress Theme From Static HTML: The Footer FileCreating wordpress theme from html 400
    In this series, you've been learning how to create a WordPress theme form static HTML. Up to this point, you have: prepared your markup for WordPress converted your HTML to PHP and split your file into template files edited the stylesheet and uploaded your theme to WordPress added a loop to your index file added meta tags, the wp_head hook and the site title and description to your header file added a navigation menu added widget areas to the header and sidebar. Read More…
  • Code
    Theme Development
    Creating a WordPress Theme from Static HTML - Adding WidgetsCreating wordpress theme from html 400
    In this series, you've learned how to convert a static HTML file to a WordPress theme and edit the header file. So far you've: prepared your markup for WordPress converted your HTML to PHP and split your file into template files edited the stylesheet and uploaded your theme to WordPress added a loop to your index file added meta tags, the wp_head hook and the site title and description to your header file added a navigation menu. Read More…
  • Web Design
    UX
    Walk Users Through Your Website With Bootstrap TourTour retina
    When you have a web application which requires some getting used to from your users, a walkthrough of the interface is in order. Creating a walkthrough directly on top of the interface makes things very clear, so that's what we're going to build, using Bootstrap Tour.Read More…
  • Code
    Theme Development
    Creating a WordPress Theme From Static HTML: Creating Template FilesCreating wordpress theme from html 400
    In the first part of this series, I showed you how to prepare your HTML and CSS files for WordPress, ensuring the structure would work, the code was valid and that the correct classes were being used. In this tutorial you'll learn how to take your index.html file and split it up into a set of template files for use by WordPress.Read More…
  • Code
    Theme Development
    Creating a WordPress Theme From Static HTML: Preparing the MarkupCreating wordpress theme from html 400
    Last year I did a small (and admittedly very un-scientific) survey among other WordPress developers. What I wanted to know was this: When they built their first WordPress theme, how did they do it? Did they hack an existing theme or did they start with their own static HTML and turn it into a theme? The majority of people I spoke to used the second approach - they were all experienced frontend developers who had built sites using HTML and CSS, and found it easiest to take their existing HTML files and convert them to a theme. Two of the people I spoke to were lecturers or teachers, and told me that this is the approach they use with students. So in this series I'm going to show you how to do just that.Read More…