Modified 2020-03-01T18:20:31Z

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

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:

• A variable s, is it denoting string, solution, solver, splitter, stream, supplier, ...?
• A variable m, is it denoting macro, message, member, min, max, map, mandatory, ...?
• A variable r, is it denoting result, request, response, rating, rate, root, rights, random, rule, ...?
• A variable c, is it denoting connection, controller, calculator, class, computer, converter, consumer, character, caller, consignment, consignor, consignee, card, customer, context, ...? And no, it is not better with con (connection, controller, converter, consumer, consignment, consignor, consignee, context, ...).
• A variable d, is it denoting domain, digit, decorator, decimal, decrease, done, decade, delimiter, decision, ...? And no, it is not better with dec (decrease, decimal, decorator, december, decade, decision, ...).

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

Often in programming lectures you hear things like: Let us call it val, standing for value, Let us call it ses, standing for session, Let us call it el, standing for element or Let us call it e, standing for event. Why not call the variables value, session, element and event then? That would be much easier and you would not have to explain what your variables stand for all the time. As soon as you have to explain what your variables stand for, you have failed.

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.

Working with units

It is important to always specify a unit when needed. When a number denotes the length of a list or similar, you do not need any unit (because there is no unit). But if the number denotes the length of a road, the temperature in a car, the mass of a person, etc, you must define a unit also. Either you have to have an extra variable containing the unit or your variable name must inform about the unit used (eg temperatureInKelvin or massInKilograms). It is not enough to say that the temperature is 15° or that your mass is 80.

The only mitigating circumstances may be if SI-units are used.