Large Teams (Part 2 of 3) - Code Style Guide

[Chuck Tomasi]

In part 1 of this series I mentioned scripts, so let's stick with that again. When working on a team, I recommend every programmer come to an agreement on, and document, a coding style guide. The larger the team, the more likely it becomes for you to end up reading someone else's JavaScript. It may sound nit-picky, but when you find yourself in that situation, it can mean the difference of hours of frustration trying to sift though another person's code. Having a standard for all programmers makes it much easier to debug and update each other's work.

Here are just a few things you might consider in your style guide:

• Indentation: If some people are using two spaces, some using four, and some using full 8 space tab stops, you could find yourself having a tough time reading and maintaining each other's code. This is particularly true since the current Javascript Editor field doesn't support tabs on some browsers (it advances to the next field - standard browser behavior for tabs).
• Get agreement on spaces around operators, function/method calls, etc.. Ex: do you prefer
  

  
  
  for (var i = 0; i < a.length; i++)
  

  
  or
  

  
  
  for (var i=0; i<a.length; i++)
  

  It's subtle, but important.
• Consider where to place curly braces "{}". Do you want them at the end of lines or on the next line? How about whether to use them on single line if/for/while constructs? They're not required by the JavaScript interpreter, but you may want to set a standard.
• Function/method/variable/class naming standards. Agree where you will be using underscores versus camel-case (e.x. myFunction()). If you aren't sure, take a look at some of the scripts provided to you from our developers.
• Last, but not least, agree on documentation and commenting. As Mary Ellen in training likes to say, "This is a note to your future self." Be kind to yourself and write down what it is your piece of code is supposed to do. In my experience, writing a block of documentation first helps me think out what I am about to do. If I cannot document it, how can I implement it? Items to consider in your documentation include:
  
  • Is everyone using a standard header/format on their methods and functions?
  • What information are you including in the header (e.g. what args are passed in and what's returned?)
  • How about short comments (// like this)?
  • Should they go on the end of the line or above the line they describe?
  
  

You get the idea. If you're going to fix it, you have to first feel comfortable reading it. A little planning now can save you a lot of headaches later.

Consider the following examples; neither is particularly "right" or "wrong". If these two authors were on the same time, then you're going to have challenges supporting each other's code.

/*
 * _getAllAffectedCIs - create an array of CI objects so we don't have to hit the DB so much
 *
 * @param chg - GlideRecord of the change request
 * @return none
 * @uses this.CI - array of CIs
 *
 */
_getAllAffectedCIs : function (chg) {

  var tc = new GlideRecord('task_ci');

  tc.addQuery('task', chg.sys_id);
  tc.query();

  while (tc.next()) {
    var ci = new GlideRecord('cmdb_ci');

    if (ci.get(tc.ci_item)) {
      this.CI.push(ci);

    } else {
      gs.log('Error: Reading CI: ' + tc.ci_item + ' on change ' + chg.number);
    }
  }
},

/*
 * _printAllCIs - create a comma separated list of all CIs found
 *
 * @param - none
 * @return str - comma separate list of CI names
 * @uses - this.CI
 *
 */
_printAllCIs : function() {

  var str     = '';
  var name = [];

  for (i = 0; i < this.CI.length; i ++) {
    name.push(this.CI.name);
  }
  str = name.join(',');

  return str;
}

_getAllAffectedCIs: function( chg )
{
    var tc = new GlideRecord ('task_ci');
    tc.addQuery ('task', chg.sys_id);
    tc.query ();
    while (tc.next () )
    {
        var ci = new GlideRecord('cmdb_ci');
        if (ci.get (tc.ci_item) ) {  this.CI.push (ci);  }
        else {  gs.log ('Error: Reading CI: ' + tc.ci_item + ' on change ' + chg. number); }
    }
},

_printAllCIs : function()
{
    var str = '';
    var name = [];
    for( i=0; i<this.CI.length; i ++ )
        name.push (this.CI.name);
    str = name.join(',');
    return str;
}

Which do you find easier to read? Why? No write that down in a style guide - even if you are the entire team. It will give your successors something follow.