Comments and layout

Comments and consistent code layout (such as indentation) are essential to creating readable code.

Comments

A comment is part of the file which is ignored by the compiler or interpreter. It is a place to add extra information for humans reading the file. Different languages have different ways of including comments. C, C++, Java, C# and others all use the same style. The have single line comments, so that everything after the // to the end of the line is a comment:

int x = 3;   // The rest of this line is a comment

They also have block comments, so that everything between the / and the / is a comment:

/*
 Everything between these delimiters is a comment.

 Even though it spreads over several lines.
*/

int y = 1; //This line is code

Other languages have different ways. For example in Python:

x = 3   # The rest of this line is a comment

#
# Python doesn't have block comments.
#
# You can pretend it does by putting a # at the start of each line.
#

Comments are used in several different situations.

File headers

A file header is a comment block placed at the start of each file. It usually contains information such as:

• The name of the project.
• The name of the file (useful if you print the code out).
• A summary of what the file contains.
• The authors name and contact.
• The software licence, copyright and owner.

There isn't really a standard format for a file header. If you are working on your own project you can put whatever information you think is useful. If you are working on a project with other people, or joining in an open source project, you should use the same type of header as everyone else.

If you are putting your software on Github or another open source site, of course you need to think carefully about the contact information you supply. It isn't necessary to use anything other than an anonymous username if you don't want to.

Documentation comments

Documentation comments are probably the most important comments. You should always try to add them, and make sure they are correctly formatted.

These comments are added at the start of every function. They may also be added to other important items such as global variables, classes and modules.

The great thing about these comments is that, for most languages, there is free software available which can go through all your source code, pull out the comments, and produce neatly formatted and cross-referenced project documentation without you having to do any extra work at all. For large projects this saves a huge amount of time. It also helps to keep the project documentation up to date - all you need to do is make sure that if you change a function you update the comment, and everything else is automatic.

Here is an example documentation comment. The @param indicates a parameter. This is the style for Java documentation, look up what to do for other languages:

/**
 * Save an image as a PNG file
 *
 * @param width in pixels
 * @param height in pixels
 * @param output file name
 */
 void savePNG(int width, int height, String filename) {
 ...
 }

Code comments

Comments are often used to explain what the code is doing. These types of comments are usually mixed in with the code, like this example:

data = [2, 5, 6, 1, 9]

# The average (mean) is found by adding up all the data values
# and dividing by the number of items
mean = sum(data)/len(data)

In this case, although the code itself shows the calculation, the comment tells us how the calculation is being performed.

"Commenting out" code

Sometimes, comments are used to temporarily stop code from executing. This is often useful while developing code, or when trying to fix bugs.

For example suppose you had some code like this:

getInputs()
calculateResult()
printAnswer()

Somewhere the code is crashing. There are many ways to debug the code, but one quick way to narrow it down is to comment out part of the code:

getInputs()
#calculateResult()
#printAnswer()

If the code still crashes, it tells you that the problem must be in getInputs. If not, the problem must be somewhere else.

Avoiding comments

Comments are very useful, but remember that you don't have to comment every single line of code. Sometimes it is better to let the code speak for itself.

Avoid comments that just repeat the code:

a = a + 2    # Add 2 to a

{{% orange-note %}} There is nothing wrong with writing a comment to explain why the code is adding 2 to a. {{% /orange-note %}}

If you find yourself writing a comment to say what a variable if for, or what a function does, it might be worth considering renaming the items so that no comment is needed. For example:

r = 2               # Radius of circle
a = calculate(r)    # Calculate area of circle

This might be better as:

radius = 2
area = circleArea(radius)

Code layout

You should always layout your code in a neat and consistent way. It isn't just about looking more tidy, it makes it more readable, which in turn means you are less likely to make mistakes and introduce bugs. Consider this code:

if (x < 10) {
    if (x < 5) {
        processSmall(x);
    } else {
        processLarge(x);
    }
}

This is clearly a nested if statement. If x is less than 5 it calls the small function, if x is between 5 and 9 it calls the large function, and if x is 10 or greater it does nothing.

Here is the same code, with the layout messed up a bit. This code does exactly the same as before, but at first glance it might appear to do something different:

if (x < 10) {
    if (x < 5) {
        processSmall(x);
} else {
    processLarge(x);
}
}

Here it is with the layout completely messed around. It still does the same thing, but it is very difficult to read:

if (x < 10) { if
(x < 5) { processSmall(x); }
else { processLarge(x); } }

Some tips for indention and code layout are:

• Choose a style ans stick to it.
• Decide how many spaces you are going to use for indentation, and always keep it the same. Most people use 4, or maybe 2, spaces for indentation.
• Avoid using Tab characters, use spaces instead.

The last point is important because some editors will replace Tab characters with spaces, but the number of spaces might not be what you intended.

If you are working on a project with other people, it really is a good idea to agree to all use the same layout. That way, if you copy code from one file to another, it will always look right.

Don't worry too much, though - many code editors or IDEs will automatically format your code with a single key press (often CTRL-SHIFT-F).