Source Code Comments

Coding Techniques; Software Development; Software Engineering

Source code comments are annotations that are used to explain the purpose and structure of a computer program's code. The use of appropriate comments facilitates the efficient creation, debugging, and maintenance of computer programs and enables programmers to work together more effectively.

Anyone familiar with the syntax of a computer language can read a computer program's source code to gain a rudimentary understanding what a statement or series of statements does. However, the code itself cannot reveal to a reader why a certain statement was used or the overall purpose of an entire program or section of code. This can make code difficult to understand, debug, and maintain, especially when it grows long and complex and is accessed by multiple people.

To address this problem, programmers use a technique called annotation. This is the process of adding comments to code to make programs easier to understand, modify, debug, and maintain. Computer code can be annotated in several ways. For example, a comment may be used to explain why a certain command or variable was used. Comments can also be used to describe functions, subroutines, classes, and methods. For this reason, comments are an important component of a project's software documentation. They are considered internal documentation, as they are included alongside the source code itself. In contrast, external documentation is kept separately, possibly as a digital file or a printed booklet.

Comments are written in plain language, not in the syntax of a computer language. Each computer language provides its own syntactical rules that allow the program, and anyone who is reading the program, to distinguish comments from executable lines of code. In many common programming languages, including C, C++, Java, and JavaScript, a comment is indicated by two forward slashes preceding the text of the comment:

// This is a comment.

All text contained within a comment is ignored by the compiler. Because of this, comments can be used to aid in testing and debugging code. For example, if a section of code is included in a comment and the error no longer occurs, the developer knows that the error is in that section of code.

Creating effective and useful comments is extremely important in real-world programming environments, which typically include teams of programmers working together on complex applications. As such projects are usually developed by multiple people over many weeks, months, or even years, proper use of comments allows programmers to quickly understand the purpose of code that was written by other programmers at other times. A lack of comments can make complex programs extremely difficult to understand. If appropriate comments are not provided, even experienced programmers will need to devote large amounts of time and effort to understanding the existing code before modifying it. Good comments form a basis from which all the components of a program and their interactions can be easily understood, greatly increasing the efficiency with which applications can be developed and updated.

The ability to create effective and useful comments is an important skill. Comments should not simply restate what a block of code does, but should focus on explaining why it does what it does and what its relationship is to the overall structure and function of the program. Developers must be committed to including appropriate comments in their code, and development methodologies must support proper commenting. Testing and quality assurance efforts should include verification that useful comments are being used.

While some programmers believe well-written source code explains itself, most agree that comments are critical to nearly all projects. Programmers focus on writing effective and efficient code that is syntactically correct. However, the inherent limitations of programming languages make it difficult to describe code fully without using comments, especially on large projects. The consistent use of appropriate comments provides significant benefits to programmers and results in greater efficiency, reduced costs, and the development of more robust and effective code. It is therefore important for anyone interested in computer programming to understand the application of comments and to familiarize themselves with any rules for comment formatting that are specific to either the programming language or the project at hand.

—Maura Valentino, MSLIS