How readable is your code?
Often programmers will work on each other's code. So you need to write your code so that it 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)
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:
| Language | Symbol used to indicate commentary |
| Reference Language | |
| Python | |
| Visual Studio | |
| LiveCode | |
| TrueBasic | |
| HTML | |
| JavaScript | |
| CSS | |
| Language | Reference Language |
|---|---|
| Symbol used to indicate commentary | |
| Language | Python |
|---|---|
| Symbol used to indicate commentary | |
| Language | Visual Studio |
|---|---|
| Symbol used to indicate commentary | |
| Language | LiveCode |
|---|---|
| Symbol used to indicate commentary | |
| Language | TrueBasic |
|---|---|
| Symbol used to indicate commentary | |
| Language | HTML |
|---|---|
| Symbol used to indicate commentary | |
| Language | JavaScript |
|---|---|
| Symbol used to indicate commentary | |
| Language | CSS |
|---|---|
| Symbol used to indicate commentary | |
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 James Bond 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 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 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 having to work out what each line of code is doing.
Meaningful identifiers
Making sure you use variable names that describe what the variable contains is very important. 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 lots of different things. It is always better to use names that relate to the value you are going to store.
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.
