Comments in C Programming: Placements and Rules

In C programming, comments are an essential tool for enhancing code readability and maintenance. However, there are strict rules regarding their placement, especially where they cannot be inserted. This article aims to clarify when and how comments can be added in C, particularly addressing the issue of inserting comments in the middle of a statement.

Types of Comments in C

C programming language supports two types of comments: single-line comments and multi-line comments, each with its own syntax and usage.

Single-Line Comments

Single-line comments in C start with // and continue until the end of the line. They are often used for brief remarks or explanations within the code. Here is an example:

#include 
int main() {
    int a  5 // This is a single-line comment
    int b  10 / This is a multi-line comment
                  that spans multiple lines /
    // The following line will cause an error if we try to comment mid-statement
    int c  a / comment / b // This will not compile correctly
    printf(...)
    return 0
}

In the example above, attempting to insert a comment in the middle of the int c a / comment / b statement would lead to a compilation error. It is best to place the comment on a separate line above or below the statement for clarity and correct syntax.

Multi-Line Comments

Multi-line comments start with /* and end with */. They can span multiple lines and are often used for more detailed explanations or when multiple lines of text are needed.

Placement of Comments

Comments can be placed anywhere whitespace is permitted outside of string literals. The preprocessor replaces all comments with a single space character. C11 specifies this in Section 5.1.1.2 paragraph 1. In translation phase 3:

The source file is decomposed into preprocessing tokens and sequences of white-space characters including comments. A source file shall not end in a partial preprocessing token or in a partial comment. Each comment is replaced by one space character. New-line characters are retained. Whether each nonempty sequence of white-space characters other than new-line is retained or replaced by one space character is implementation-defined.

This is also true in C89 and C99. This differs from some traditional implementations of the preprocessor prior to ANSI C, where comments were deleted entirely, leaving nothing behind, and allowing for tricks such as token concatenation. ANSI C replaced this with the single-space rule and added a separate preprocessor operator # for explicit token concatenation.

Examples and Considerations

Coding a comment within a statement like this:

#include 
double whee() { / wahoo! / {
    printf / yippie! / / yay! / 
    return 0
}

This will compile and run without warnings. However, it might be confusing to read but it will work. The key takeaway is that placing comments mid-statement will disrupt the code's syntax and result in compilation errors.

Another consideration is the fact that you cannot split a token using a comment, such as pr//intf, which would result in pr ntf, two tokens, and not valid syntax. This is more lenient in pre-ANSI-C compilers but is not allowed in C89 and beyond, which results in pr ntf.

Conclusion

Understanding the rules and proper placement of comments in C programming is crucial for maintaining code clarity and functionality. By adhering to the guidelines mentioned above, programmers can ensure their code is both readable and error-free. Whether you choose to use single-line or multi-line comments, the key is to avoid inserting them in the middle of a statement to maintain syntactic correctness.

Keywords

C programming comments, comment insertion, multi-line comments, single-line comments