Coffee = Closers; Comments == Coders.

• April 5, 2018
• Matthew F. Fox
• 4 min

As a developer, you spend a lot of time in front of an IDE writing, maintaining, and improving code. Code that provides elegant, direct, and efficient solutions for business problems.

While the best code may be self-documenting, even the clearest written code should include documentation to assist other developers who will work with it. Always keep in mind that the code tells you how, the comments tell you why.

Good Code Deserves Good Comments

Opensource.com ran a poll of nearly 500 developers with one question: how frequently do you comment your code?

The question is largely subjective as it’s determined by opinions influenced by each developer’s experience and projects being worked on, but the results are encouraging. About 1/3 of the poll’s participants feel that their comments are adequate, while a slightly larger percentage see room for improvement – and there is always room for improvement.

Clear and concise comments are a standard for development projects here at Valiant. It enables our teams to spend more time building solutions and making improvements to both internal and client projects, and prevents spending time trying to figure out exactly what a piece of code is designed to accomplish.

A Real-Word Example

Here’s a perfect example – it’s a JavaScript function that we commonly use in projects that depend on jQuery, with a block comment that follows the JSDoc comment syntax:

/**
 * Returns promise from AJAX call.
 * Use this function in place of standard AJAX calls to keep
 * code easily managed and readable.
 *
 * @since 0.1.2
 * @requires jQuery
 *
 * @param params  json object containing parameters used by $.ajax()
 * @returns {*}   promise object
 */
function doAjax(params){

    var defaults = {
        dataType: "json",
        method: "GET",
        async: true,
        tokentype: 'Bearer'
    };

    // merge contents of default and param objects in to new object.
    var parameters = $.extend(defaults, params);

    return $.ajax({
        beforeSend: function(xhr){
            // set authorization header if token exists.
            if (parameters.token){
                xhr.setRequestHeader('Authorization', parameters.tokentype + ' ' + parameters.token);
            }
        },
        method: parameters.method,
        url: parameters.url,
        data: parameters.data,
        dataType: parameters.dataType,
        async: parameters.async
    });
}

A quick glance at the comment block explains the purpose of the function, states it first appeared in version 0.1.2 of the library it’s a part of, requires jQuery, and accepts a JSON object as a parameter. This makes it much easier to understand the function as you read it for the first time – and even better, when you’re improving code you may have written some time ago.

Forming a consistent practice around comments will make your code easier to read, period – but that’s not all. Following a syntax, like JSDoc, will provide the added benefit of documentation generators that will read your comments and format them in to HTML-based documents. Not only are these handy to have around, they also are the perfect way to help get new team members up to speed in less time.

Sure, nothing beats browsing code to understand how it works; you’re just providing them with a map as they begin their journey in to a new project, Zelda style.

Comment Before You Code

Another helpful practice is to write comments before you code. I’ve been using comments as a starting point for code for the past year or so, and it’s helped me improve the overall quality of the code I write.

Think of it as a blueprint; a very minimal description of what’s to come and nothing more. It forms a plan of execution, and can lead to various functions and other blocks of code being written in an order that helps tell the story of the solution you’ve written.

Tabs vs. Spaces: Consistency is Key

Making the appropriate style choices in your code is equally as important, and no topic causes the hairs to raise on the back of a developer’s neck quite like tabs vs. spaces. The war of tabs vs. spaces is one that will never end. It’s been a topic of discussion for years, and StackOverflow even found that, by way of their 2017 Developer Survey, developers using spaces make more money than developers that use tabs.

If you like tabs, use tabs. Prefer spaces? That’s cool. No matter what you choose, the most important thing is to be consistent. While your code may look a bit different from one editor to the next, code that uses a consistent pattern will always be easier to read.

Editorconfig To The Rescue

Ready to end the timeless argument of tabs .vs spaces and get some work done? Good. Work with your team to form a standard and enforce it with software.

Editorconfig helps developers define and maintain consistent coding styles between different editors and IDEs. It’s a single text file containing preferences for defining coding styles, supported by many text editors and IDEs including SublimeText, Notepad++, PhpStorm, and Visual Studio Code via native support or plugins. 

You can download a copy of Valiant’s default .editorconfig file for LAMP projects from Github.

In the end, it all boils down to readability. Write code that is easy to understand and work with, and you’ll spend less time fixing bugs, figuring out how things work, and more time writing more… comments. Whether saving a princess or a writing a new compression algorithm, write well-formatted code and comments that’ll tell the story of your solution – for you, and the team members to come.