What is self documenting code?

Let’s first take a look at code that is not self documenting.

var x = 1;
if (y === true) {
  x += 1;
}

vs 

let count = 1;
if ( loggedInSuccessfully === true ) {
  count += 1;
}

Even though this is a very simple example you can see right away that in the first example it is unclear what x is used for. You may be able to figure it out in context of the rest of the program but you might not.  In the second example it’s much easier to deduce that we are incrementing count every time someone has logged in successfully is true.

Now imagine this was a more complex function in the code.

function z () {
  let x = [];
  let y = _.keys(s);
  tables = _.map(y, function (y) {
    return function () {
       return z(y);
     };
   });
 return sequence(x);
}

vs

function createTables () {
  let tables = [];
  let tableNames = _.keys(Schema);
  tables = _.map(tableNames, function (tableName) {
     return function () {
       return createTable(tableName);
     };
  });
 return sequence(tables);
}

In this slightly more complex example there is only one clue as to what you might be doing in that first function. It’s the keyword sequence and even that just gives you a hint that they might be using the when promise library. This would require that either you wrote the horrible code so you know what it does or a decent amount of time trying to use it with in the code base.

The second one, well it looks like it wants to create a table based off an array of tables using the a function called keys to read the table names from a Schema variable. Then it builds that array by using a function called map to go over the tableNames schema, returning a function that calls the createTable function on the passed in tableName. Then we return the sequence output on that array we just finished building.

Even if that second paragraph does not make complete sense it will let you discuss the function with other programmers or support forums in a more intelligent way. That is the main benefit of self-documenting code, however it will also help you remember what you were doing when you have to revisit the code later.

One of the side effects of self-documenting code are potentially very long variable names. I have seen things along the lines of thisWillBeWhereWeStoreTheResultsOfTableCreationErrors. A bit hard to swallow but I have a pretty good idea what type of data I should expect to retrieve or store there.

Breaking it down

Reasoning

• Create readable and understandable source code
• Make it easier on the next guy (or your memory)
• Keep code cleaner with less comments
• Keep the documentation inside the code

Practices

The main goal is to make it as human readable as possible. Instead of single word variables use a phrase that is more closely tied to the meaning. The other aspect is to use white space to keep the structure consistent and reduce obfuscation of the algorithm being used.

Gotchas

There are things to watch out for, if working with a team, is to maintain uniformity, consistency and to make sure it doesn’t get too far out that it becomes a novel to go through your code.

If you stick to these basic guidelines you will do better than many professional developers out there. If you want to learn more head over to the wiki page.