Maintainable code

2. Comments

Programming languages generally allow you to mark blocks of text within a program which the computer will ignore when it runs or compiles the code. These are called 'comments'. They can explain what a particular line or block of code is doing.

By using comments, people who look at your code will be able 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.
• Procedures and subroutines - 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 what data each subroutine 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.