Comment Programming

Software Development; Coding Techniques; Computer Science

Comments are annotations that are used to explain the purpose and structure of the code used to create computer programs. The use of appropriate comments makes it more efficient to create, debug, and maintain computer programs and enables programmers to work together more effectively.

Anyone familiar with the syntax of a computer programming language can read the code itself to gain a basic understanding what a statement or series of statements does. However, the code itself cannot reveal to a programmer why a statement or series of statements was used or the overall purpose of an entire program or a section of code. This can make computer programs difficult to understand, debug, and maintain. To address this problem, programmers use comments to annotate the code that they create.

Comments can be used to annotate many types of computer code. For example, an explanation of why a certain command was used can be provided in a comment. Comments can also be used to describe functions, subroutines, classes, and methods, and to explain why variables are used.

Comments are written in plain language, not in the syntax of a programming language. However, each programming language provides its own rules that allow the program to distinguish properly marked comments from executable lines of code and to ignore them. For example, a comment might be distinguished by using two forward slashes before the text that makes up the comment, as follows:

There is no good substitute for annotation. Although this takes time, the time spent annotating code can greatly reduce the time spent on debugging and maintenance. Comments may be added before, while, or after the code is written. Updating comments to reflect changes in the code is just as critical as adding them at the start.

Because annotation takes valuable programming time, learning to create short but effective and useful comments is an important skill. Comments should not simply restate what a line or block of code does, but rather focus on explaining why the code does what it does and how it relates to the overall structure and function of the program. Consider the following comment associated with the declaration for the variable age.

This comment does not convey any meaning or information that could not be determined from the code statement itself. A more effective comment could be written as follows.

This comment explains succinctly why the variable is being declared and how the variable functions within the program.

Comments are expected in several places. An entire program typically has a comment at the beginning. Called a “header comment,” this states the author, the date of creation, the date of last update, the purpose of the program, and its function. Each function should be called out, as should any single line of code that is not intuitive. Too many in-line comments may indicate that the code is overly complex. Or, it may mean that the names for variables, constants, functions, and the like are not descriptive enough.

Creating effective and useful comments is extremely important in real-world programming environments, where teams of programmers often work together on complex applications. For example, an application used to track client data for a major insurer might consist of tens of thousands of lines of code containing numerous variables, methods, classes, commands, and other statements. Such projects are usually developed over many weeks, months, or even years by dozens of programmers. Thus, proper use of comments allows programmers to quickly understand the purpose of and interactions among lines of code written by other programmers and at other times. This greatly increases the efficiency with which applications can be developed and updated. Consider the following code example in the Visual Basic language:

Along with comments, adding line breaks and indenting nested blocks of code make the code easier to read and understand.

Programmers focus on writing effective code that has correct syntax. However, the inherent limitations of programming languages make it difficult to describe code fully without using comments, even if the program has few functions and a single author. Larger projects that provide complex functionality and involve multiple programmers working together are exponentially more difficult to manage. The consistent use of appropriate comments provides significant benefits to programmers and results in greater efficiency, lower costs, and more robust and effective code.

—Maura Valentino, MSLIS