Logo for Nemo Nisi Mors
Friends in need
Random Quote
I always turn right because then I can't go wrong.
Toby Tanser
Modified 2019-09-08T10:30:37Z

Some examples of when it is good to walk that extra mile when programming. Sometimes you will avoid performance problems, sometimes you will minimize the risk of errors, sometimes you will just make the code more understandable for a human being.

Minimizing risks

Looping through the elements in an array can be achieved in many, many ways. Here are four examples with subtle differences. Sorted increasingly by risk of getting "off-by-one"-problems.

for (i = 0; i < arr.length; i++) {
    x = arr[i];
}

for (i = 0; i <= arr.length - 1; i++) {
    x = arr[i];
}

for (i = 1; i <= arr.length; i++) {
    x = arr[i - 1];
}

for (i = 1; i < arr.length + 1; i++) {
    x = arr[i - 1];
}

Note: Since I am a computer scientist, the indices of the arrays are of course zero-based in the examples.

Clarity for humans

Computer vs human

Human-readable code is an art. Compare these two code-blocks:

for(i=0;i<names.length;i++){name=names[i];print("name is "+name);}

and

for (i = 0; i < names.length; i++) {
    name = names[i];
    print("name is " + name);
}

Did you easily see that the blocks are identical?

A computer does not need redundant whitespaces to be able to read code. So extra spaces or newlines will not be helpful for a computer.

But, we as humans are not as good as computers when reading code. Hopefully you are programming and writing code for your colleagues and not mainly for the computer. As a great programmer you know that a large part of a programmer's life consists of making code readable for humans. The easy part is coding for your computer, the hard part is coding for your colleague. Great programmers know that striving for complex one-liners is not a good thing.

Programs must be written for people to read, and only incidentally for machines to execute.

Hal Abelson and Jerry Sussman

Any fool can write code that a computer can understand. Good programmers write code that humans can understand.

Martin Fowler

Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live.

Martin Golding

Spacing

Using space in your code is the same as when writing ordinary texts. You need whitespaces, paragraphs, sections, chapters, etc, otherwise your readers will go mad. Do you think it would be fun to read a book with no chapters or paragraphs?

Use blank lines to divide your code, in the same way you use paragraphs when writing texts. Using blank lines have never harmed anyone, but not using blank lines surely have.

Indentation

One of the most important parts when programming is to indent your code correctly. Missing this will surely make your readers go mad and stop reading your code.

In some programming languages (eg Python), the logic may be completely changed if you indent incorrectly.

Capital letters and punctuations

Use punctuation marks (the use of certain marks to clarify meaning of written material), so your code will be more understandable.

When writing comments, I advise to always write complete sentences, i.e. start with a capital letter and end with a full stop. This will make it easier to see that nothing is missing before the first or last words.

In this first example, it is easy to see that the comment probably contains all the information that the author intended.

// Weight in kg at sea level.

In this second example, it is harder to see if the comment contains all the information that the author intended. You can not be sure that some things aren't missing.

// weight in kg at sea level

In this third example, you get really confused.

// eight in kg

In this last example, you actually are more convinced, still confused though, that this is the comment the author intended.

// Eight in kg.

Many programming languages need your semicolons to be syntactically correct so the code can be understandable for the computer. Why being lazy when writing for humans?

Naming

Yes, you can name all your variables and functions like a, b, c, ..., x, y, z, a1, b1, c1, ..., x1, y1, z1, a2, b2, c2, ..., and that will probably be syntactically correct. But why? You should instead be thankful that smart people have invented explicit naming so you are able to name your variables and functions in a better way.

Let us take a few easy examples:

The modern IDEs have no problems in helping you writing longer names.

There are tools you can use if you must obfuscate or minimize your code, but please do not be a programmer that writes obfuscated or minimized code directly from your keyboard.

Single character variables

Sometimes it may be okay to use single character variables. Loop variables may be denoted i, j, k. Integer variables may be denoted m, n, especially when accompanied by documented formulas or algorithms. It is the same with floating point variables denoted by x, y, z.

Abbreviations

There are not many occasions when using unestablished abbreviations are a good choice. Yes, HTML, XML, FTP, HTTP, API and the likes, are probably good choices to use.

But if you have domain-specific things like CarColorFactory and NativeNodeModule, it may not be a good choice to abbreviate these like CCF and NNM everywhere in your code, since people non-fluent in your domain-specific language will have a hard time understanding the code. Remember that most people, including your colleagues, are non-fluent in domain-specific languages in the beginning.

Do not use random characters in your variables either. If you want a variable denoting a number, use number or n, but variants like nbr, num or no are just confusing.

Review your code

The most important part is to always review your code before leaving it. Ask yourself, "Does this code make sense to others?", and if the answer is "No", take the time to refactor the code.

First published by Anders Gustafson 2019-07-23