Thanks to a number of open source contributors, I released WP Audio Player 1.3 to the WordPress plugin repository. For one of the pull requests, I mentioned the following:

I always terminate my blocks with a closing comment. Please keep this in the file.

Travis Northcutt also asked me about it via Twitter:

When it comes to writing code, I try hard to make sure that anything I do that’s outside of the normal coding conventions for a given platform has a rationale behind it.

Case in point: Ending my terminating braces with code comments.

Commenting Code Blocks: Terminating Comments

Simply put, I terminate blocks with code comments simply because it makes finding the matching closing brace to its opening brace much easier regardless of the IDE that the developer is using.

To be clear, I’m don’t particularly subscribe to the arguments for or against any given language. You won’t hear me strongly defending PHP nor will I be found arguing about why an aspect of VB.NET is lame.

It’s not so much that I don’t get said arguments – because I do – but I’m more concerned with working within whatever constraints of the platform I have and trying to do a good job within them not only for myself, but for whatever developers end up working with the code that I’ve written.

In the most simplistic example, let’s say that you have a foreach loop responsible for iterating through the contents of a collection:

foreach( $collection as $item ) {
    // Do work...
} // end foreach

This is easy enough to follow that it seems pointless to add a comment to the terminating block. After all, it’s clear where the loop ends, right?

Now, let’s say that the given loop is responsible for setting the current item to -1:

foreach( $collection as $item ) {
    $item = -1;
} // end foreach

Still trivial, right?

Now let’s say that we want to set the current item equal to to -1 if and only if the current environment’s foo_condition() is currently true.

foreach( $collection as $item ) {

    if( foo_condition() ) {
        $item = -1;
    } // end if

} // end foreach

Now it’s slightly more complicated, but still easy enough to follow.

But let’s say that  foo_condition() isn’t true. And let’s say that there’s a separate collection through which we need to iterate.

And then, during the nested loop, we need to compare the current $item‘s value to the current foo value and, if it’s not the same, then we’ll assign it to the current item.

Even describing it is a little cumbersome, isn’t it?

Anyway, the code would then look something like this:

foreach( $collection as $item ) {

    if( foo_condition() ) {
        $item = -1;
    } else {

        while( foo_condition() ) {

            if( $item->value != get_foo_value() ) {
                $item->value = get_foo_value();
            } // end if

        } // end while

    } // end if

} // end foreach

At this point, the code is relatively simple in that it’s not doing anything complicated, but there’s a lot of nesting going on. It’s not at all unreasonable to assume that a third condition could be introduced this making this particular block of code exceed the height of my IDE’s viewport.

On top of that, let’s say that I’ve pulled code that uses spaces instead of tabs and terminating braces aren’t properly aligned (let alone the rest of the code).

Finally, let’s say that someone pulls my code but their IDE doesn’t allow me to collapse blocks or renders vertical lines from the opening and closing of a block.

If it’s one – or all – of the above, it can be a pain to work with, so adding a single comment to the terminating brace of a code block can go a long way in making the code just a bit easier to read especially in an open source culture.

What About Alternative Syntax?

Of course, PHP offers alternative syntax such that the above code could be written like this:

foreach( $collection as $item ):

    if( foo_condition() ):
        $item = -1;
    else:

        while( foo_condition() ):

            if( $item->value != get_foo_value() ):
                $item->value = get_foo_value();
            endif;

        endwhile;

    endif;

endforeach;

At first glance, this is actually like combining the code comments and the curly braces from above, right? On top of that, it’s also similar to white-space delimited languages like Ruby, Python, and so on.

But this does nothing to address any of the problems above. In fact, I’d argue that this is actually worse because most IDEs won’t match an endif to its opening : at all.

A Word About Legacy Code

In the comments, Gary pointed out that the example given above is actually more of a ‘code smell’ than a best practice for writing code primarily because a lot of the deep nesting can be refactored into their own functions that result in significantly easier code to read and maintain.

As such, I wanted to make sure that I clarify here that I find this practice particularly useful when working with an existing codebase or in legacy code when it’s not always feasible to refactor an entire system.

This is one of those things that’s a small step towards improvement without completely derailing a project into an time suck of oblivion.

That said, it’s still something that I’ve begun to do out of habit if for nothing else to identify where functions and blocks end and to be consistent with how I’ve been commented my LESS files and my front end templates.

So, after all of the above, that’s why I terminate my blocks with comments. I’ve found that it makes reading code just a bit easier to follow regardless of the environment.