Our industry moves so fast that just to stay on the curve, let alone ahead of it, you need to spend a considerable amount of time reading other peoples code. Whether that be in code reviews, gists, or open source projects, you can glean a lot of invaluable information about new technologies, protocols, and techniques.

As an industry as a whole we need to understand this and write all code, even that which at first is not meant for public consumption, as self-documenting code with comments which detail, to anyone reading it, the why the code is doing what it’s doing.

Self-documenting code is code which follows commonly accepted style conventions, and uses descriptive variable, and function names. As an example, self-documenting code turns this:

function gd(p1, p2) {
  return [p1.x - p2.x, p1.y - p2.y];
}

Into:

function getDifference(point1, point2) {
  var x = point1.x - point2.x;
  var y = point2.y - point2.y;
  return [x, y];
}

It’s much easier to understand what the second function is doing at a glance vs the first.

This function is so trivial many will stop here and continue on. But trivial scripts have a way of becoming more, whether they grow into a project of their own or are copy/pasted into much larger projects where their use may not be as clear.

Lets assume for a moment that this function was copy & pasted into a larger projects utility class. Wouldn’t it be nice if it would automatically be added to the API docs?

/**
  Calculate the difference between the x and y coords of two points.

  @method getDifference
  @param {Object} point1 The first point to compare.
  @param {Object} point2 The second point to compare.
  @return {Array} The difference between the two points in the format [x, y]
*/
function getDifference(point1, point2) {
  var x = point1.x - point2.x;
  var y = point2.y - point2.y;
  return [x, y];
}

This function can now be copy and pasted into any project without any ambiguity about it’s functionality and will automatically be included in the API documentation.

To illustrate the importance of inline comments even with self documenting code. Take the following method from the Juju GUI source.

The Juju GUI has just over 65,000 lines of javascript excluding dependencies and growing fast every day. With so many developers writing code this fast it would be very difficult to understand why things were done the way they were done without the additional 17,000 lines of api comment blocks and inline documentation.

exportYAML: function() {
  var result = this.db.exportDeployer();
  var exportData = jsyaml.dump(result);
  var exportBlob = new Blob([exportData],
             {type: 'text/plain;charset=utf-8'});
  saveAs(exportBlob, 'export.yaml');
},

Using only self-documenting code you would probably be able to figure out that this function extracts some data from a database, converts it into yaml, then saves the blob to disk. Unfortunately this would have taken you at least 4x longer to parse because it doesn’t have any comments. You would also be missing some very important information from a previous bug fix. Now here it is with it’s comments:

/**
  Export the YAML for this environment.

  @method exportYAML
*/
exportYAML: function() {
  var result = this.db.exportDeployer();
  var exportData = jsyaml.dump(result);
  // In order to support Safari 7 the type of this blob needs
  // to be text/plain instead of it's actual type of application/yaml.
  var exportBlob = new Blob([exportData],
      {type: 'text/plain;charset=utf-8'});
  saveAs(exportBlob, 'export.yaml');
},

Without even reading the code you now know what the purpose of this method is which will dramatically reduce time when debugging or adding more features. More importantly however, the why of some of the code is outlined for future-you or another developer who may end up here. Without the comment regarding Safari 7 they very likely could have changed the mime type to application/yaml and introduced a difficult to find bug.

Although these examples were simple I hope I have illustrated the importance of adding comments to your self-documenting code to aid not only future-you but also any other developer who may come by and learn from your work. Thanks for reading! What commenting techniques do you use? Comment below or mention me on twitter @fromanegg.

Last week the latest version of the Juju GUI was released. With the holidays and our move from Bazaar and Launchpad to Git and Github there was unfortunately over a month from our last release. Have no fear however because this one brings with it some big changes.

One thing that anyone who has used the internet for more than a day can attest to, is that we have a lot of credentials to remember. Every new product we purchase, every new website we log into, every system in corporate networks need a unique username and password to access. To help combat the huge number of credentials we need to remember many administrators have started to implement what is known as single sign on.

Single sign on, or SSO, is the practice of having the user to log into a central system which then grants them access to multiple systems. If you have ever logged into a third party website using your Facebook, Google, or Twitter account you have used SSO. From the user perspective this is incredibly convenient because now they only have to remember a single set of credentials for multiple systems. Unfortunately SSO does little to combat users from using simple insecure passwords which, when compromised, will now give the attackers full access to a number of systems instead of just a single one.

As an additional layer of security many administrators are implementing another layer of security called two factor authentication. 2FA simply means that there are multiple techniques used to identify you when you attempt to gain access to a system. This can be in the form of a text message being sent to your phone, or a random key generated by a third party key generator which is required to be entered along side your typical username and password.

This all sounds excellent, but unfortunately it is very complicated and time consuming to implement both systems correctly and securely. To solve this issue the great people in Juju Labs at Canonical have started a project to bring instant SSO & 2FA to Juju users everywhere.

How are they going to do it? Because every system from Apache, to MongoDB requires a different technique to implement SSO & 2FA, a third party repository will be created which will house a large collection of expertly written components which will interface with the SSO & 2FA Juju Charm.

As with everything in Juju Labs this will require buy-in and support from the community to push forward. There are already three contributors out of the required five to move it to the next stage and a number of people who are very interested in seeing this become a reality. If you are interested in being able to add SSO and 2FA into your systems with a few clicks or want to lend a hand as a contributor you can flip through the slide deck below, spread the word around, or sign up as a contributor.

Instant Single Sign-On and Two-Factor Authentication from Maarten Ectors

Earlier today I talked with some of the YUI team about the Juju GUI and how we use YUI for the first ‘YUI in the wild’.

The links I mentioned in the video:

It’s been a few weeks since our last Juju GUI release which means here comes another! This GUI release brings with it the latest beta version of the Juju quickstart plugin…

Juju GUI

Our latest work focuses on making the Juju GUI a more effective day-to-day tool:

Juju Quickstart

The quickstart plugin is nearing feature completion and has a lot of great improvements.

To try out our new releases, existing users can upgrade their GUI charm to cs:precise/juju-gui-81; or run:

juju deploy juju-gui && juju expose juju-gui

…or update the juju-quickstart plugin via apt and run:

juju quickstart

New users on Ubuntu can do the following to get everything installed and start an environment with the GUI running and ready:

sudo add-apt-repository ppa:juju/stable
sudo apt-get update && sudo apt-get install juju-quickstart
juju-quickstart
## ...edit ~/.juju/environments.yaml file...
juju-quickstart

Next quickstart release will hopefully remove those last two steps.

New users on other operating systems can’t use Quickstart right now, but the Juju installation instructions can get you started, and..

juju deploy juju-gui && juju expose juju-gui

..can add the GUI to your bootstrapped environment.

Juju GUI Installation documentation can be found here.