Readable code: a guide to absolute beginners

I am a teacher, I am in contact with beginners very often and beginner developers often do not feel the necessity to write their code in a nice, cleanly indented fashion.

If you are an experienced developer, this post is not for you, it is for your juniors that struggle with making their code readable.

All those methods should be used together, not in isolation

You have been warned.

What is indentation

Code indentation is a way to write code to be more legible and to make patterns inside the code very visible. It makes reading the code and debugging it much easier.

For example:

namespace Quicksort
{
    public class HoarePartition
    {
        public static int Partition(int[] array, int first, int last, int valeurDePartition)
        {
            int i = first;
            int j = last;

            while (i >= j)
            {
                while (array[i] < valeurDePartition)
                {
                    i++;
                }

                while (array[j] > valeurDePartition)
                {
                    j--;
                }

                if (i >= j) return j;

                (array[j], array[i]) = (array[i], array[j]);
            }
            return j;
        }
    }
}

The code above is much easier to follow than if it had been written that way:

namespace Quicksort{
public class HoarePartition{
public static int Partition(int[] array, int first, int last, int valeurDePartition){
int i = first;
int j = last;
while (i >= j){
while (array[i] < valeurDePartition){
i++;
}
while (array[j] > valeurDePartition){
j--;
}
if (i >= j) return j;
(array[j], array[i]) = (array[i], array[j]);
}
return j;
}}}

Spaces, grouping, and skipping lines

Going back to the previous example, skipping lines is also a tool that allows to understand the code more easily:

namespace Quicksort
{
public class HoarePartition
{
public static int Partition(int[] array, int first, int last, int valeurDePartition)
{
int i = first;
int j = last;

while (i >= j)
{
while (array[i] < valeurDePartition)
{
i++;
}

while (array[j] > valeurDePartition)
{
j--;
}

if (i >= j) return j;

(array[j], array[i]) = (array[i], array[j]);
}
return j;
}
}
}

In this code, all indentation was removed, yet some groups of operations still stand out: we can see variable initialized together at the top, then we can see one loop ticking forward (i++) and one ticking backwards (j--).

Here is some simple advice:

• When you have some control flow or large declarations, separate those with empty lines from the rest.
• when you have comma separated sequences of things, no space before the comma, a space after is generally the norm
• If you have several operations using operators in a line, separate the operands from the operators:
  • Write sectorsize <= 0 || (sectorsize % DEV_BSIZE)
  • Do not write sectorsize<=0||(sectorsize%DEV_BSIZE)
• Do not overdo it:
  • Skipping one line is good
  • Skipping two lines can help
  • Skipping three lines rarely helps
  • Skipping more should generally not be done

Formating tools

Auto-formatting tools are very common for several programming languages.

On Visual Studio

Look in the Edit menu, in Advanced, Format Document.

On Visual Studio Code

Press F1 and type: Format Document, follow the instructions if no formater is installed.

Command-line

For C, C++, Objective-C, C# and Java you can use A-Style: http://astyle.sourceforge.net/

Comments

Look at your code, you understand it now. Imagine a beginner stumbles upon it: you may want to give him hints at what your code does or how it does it. For that you can use comments.

This depends on your programming language, so look it up and use them to add context to your code if it is not obvious.

Sharing code

You can share your code with communities if you want it reviewed or do not understand it. Here are a list of tools for that:

Any language

• Github Gist
• Pastebin

C or C++

• Compiler Explorer

Etiquette

Read these:

• https://dontasktoask.com/
• http://www.catb.org/~esr/faqs/smart-questions.html

Thanks

If you want to suggest additions to this, ask @QNeko on Telegram, or https://social.linux.pizza/@Archivist on the fediverse.