Readable code: a guide to absolute beginners

by Ludovic Lagouardette

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;
}}}
if(a < b) c;starts hereends hereif we want to insert a new line inside this expression,we need to indent that by one.if(a < b) c;->if(a < b) c;if ( a < b ) c;depending on what you consider a region, you may needto indent more than once. however, be careful, more splitting is not always bettera common indent style is the K&R style for Cif(a < b) { while(true) { c( d + 3 * e, e + 6 ); d(a, b); if( a + b < 6 && c(8, a) > 24 ) break; }}with each read arrow, you count one more indent, with eachblue one less indent.if your last line is not aligned with your first line, you havea bug, and you can readily see that: > it means some form of expression is unfinished01233222332310Another way to read it is that every time you develop an idea,you add a level of indentation on every line that develops thatidea.if(a < b) {while(true) {c(d + 3 * e,e + 6);d(a, b);if(a + b < 6&& c(8, a) > 24)break;}}programif blockwhile blockfunction callif blocklong condition012333generally one instruction blocks are frowned uponyou could indent them twice making this a 4 andpeople would accept that tooif(a < b) { while(true) { c( d + 3 * e, e + 6 ); d(a, b); if( a + b < 6 && c(8, a) > 24 ) break; }}You can also see that as making marks that show the start and end of long ideas.Lots of IDEs will actually show lines like these

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

!Those tools do not generally add or remove any empty lineThose tools may sometimes break things

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:

Thanks

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