2. Comments

Programming languages generally allow you to mark blocks of text within a program that programmers can read, but that the computer will ignore. These are called 'comments'. They can explain what a particular line or block of code is doing.

Below is a typical comment within a program, a marker such as // indicates a comment line - this changes in each computer language.

    // This will ask the user for their password
    WHILE entered_password != correct_password
         entered_password = input("Please enter password")
    END WHILE

People can use your comments to work out what it is supposed to do. Even things that seem obvious while you're writing them can be difficult to follow in a few weeks or months. So it is good practice to include comments after each of the following:

• Variables and constants - While you should use descriptive names for every variable and constant, comments can provide an extra hint about what you intend to use them for.
• Subroutines and functions - These, more than any other type of code, cause the program flow to jump around between sections. So you should include a description up-front about the data each function is calling, what it is doing to that data, and what it returns to the main program.
• Throughout the program - Good programmers include enough comments that the reader could, if they wanted to, rewrite the program following just the descriptions provided. At the same time, comments should describe what a block of code is doing overall, rather than specific descriptions of what every line is for.