EvaluationHow readable is your code?

Often programmers will work on each other's code. So it is important to write code that can be read and understood by others. You also need to be able to understand it if you come back to it months or years later.

There are a few techniques you can use to help with this:

• internal commentary
• meaningful identifiers (variable names)
• indentation
• white space

Internal commentary

Internal commentary lets a programmer add comments to their code that will not be translated when the program runs. These comments can be used to add descriptions, notes or explanations that can be read by anyone with access to the code. This is useful when working as part of a team as other programmers can get an idea of what your code is doing and why you made certain decisions.

Different languages use different symbols to start a line of internal commentary. Languages used for web development also make use of internal commentary. Some examples are:

In the reference language example shown below, internal commentary lines start with the # character and are shown on lines 1, 2 and 3.

Line 1 # This is an input validation algorithm

Line 2 # Created by Bitesizer 1 on 15/04/16

Line 3 # 0 is an accepted value for babies under 1-year-old

Line 4 DECLARE age AS INTEGER INITIALLY 0

Line 5 RECEIVE age FROM (INTEGER) KEYBOARD

Line 6 WHILE age < 0 OR age > 130 DO

Line 7 SEND “Please enter a valid age” TO DISPLAY

Line 8 RECEIVE age FROM (INTEGER) KEYBOARD

Line 9 END WHILE

Having internal commentary makes it easier to see what is going on in your program. If you are looking at someone else's code, it can save you time instead of having to work out what each line of code is doing.

Meaningful identifiers

It is important to use variable names that describe what the variable contains. Poor variable names can make it difficult to work out what is going on in your program.

For example, the use of the word ‘data’ is not meaningful:

DECLARE data AS STRING INITIALLY “ “

‘Data’ is an ambiguous term that can be used to describe many different things. It is always better to use names that relate to the value you are going to store. For example:

DECLARE surname AS STRING INITIALLY “ “

The same is true for subprograms and functions. Function names should describe what the function does. 'Function2' is not a great function name for a function used to calculate an average score. 'CalculateAverage' would be much better.

Indentation

Indentation means moving parts of your code that form the content of constructs such as loops or if statements to the right so it's easier to see the overall structure of the code. Using indentation can make your code much easier to read.

In some languages (e.g. Python) indentation is mandatory. Missing it out will result in syntax errors.

Often when debugging (looking for errors in your code when you have a problem), proper indentation of your code will help manually identify errors quickly. Here's an example of poor indentation...because there is no indentation at all:

IF age < 17 THEN

SEND “You are too young to drive” TO DISPLAY

ELSE

SEND “You are old enough to drive” TO DISPLAY

END IF

Here's the same piece of code correctly indented. It is now much easier to read and see what is going on at a glance:

IF age < 17 THEN

SEND “You are too young to drive” TO DISPLAY

ELSE

SEND “You are old enough to drive” TO DISPLAY

END IF

White space

Like indentation, white space is used to help make it clear where code is placed. White space is used to separate different subprograms and functions so that it is easier to see each module (section) of code.

The listing shown below contains no white space to separate the sections of code.

DECLARE firstname AS STRING INITIALLY “ “

DECLARE surname AS STRING INITIALLY “ “

DECLARE age AS INTEGER INITIALLY 0

RECEIVE firstname FROM KEYBOARD

RECEIVE surname FROM KEYBOARD

RECEIVE age FROM KEYBOARD

WHILE age <0 OR age > 100 DO

SEND “Invalid age, try again” TO DISPLAY

RECEIVE age FROM KEYBOARD

END WHILE

Using White Space would make this code more readable.

DECLARE firstname AS STRING INITIALLY “ “

DECLARE surname AS STRING INITIALLY “ “

DECLARE age AS INTEGER INITIALLY 0

RECEIVE firstname FROM KEYBOARD

RECEIVE surname FROM KEYBOARD

RECEIVE age FROM KEYBOARD

WHILE age < 0 OR age >100 DO

SEND “Invalid age, try again” TO DISPLAY

RECEIVE age FROM KEYBOARD

END WHILE