6.5 Types of Comments

Comments can be either global or internal.

6.5.1 Global Comments

Global, or strategic, comments occur outside of function definitions and provide structural or algorithmic information about the file or program. Global comments are almost always special Doxygen comment blocks. See Section 6.6 "Introducing Doxygen".

6.5.1.1 Comments are allowed on structure member declarations:

typedef struct {
  EFI_SAMPLE_STRUCTURE *StructurePointer; ///< Sample comment #1
  UINT64               SimpleVariable;    ///< Sample comment #2
} EFI_STRUCTURE_NAME;

6.5.2 Internal Comments

Internal, or tactical, comments occur within the body of a function definition and are used to convey special information of use to someone actively reading the code. These comments are never special Doxygen comments.

6.5.2.1 For internal code comments, use C++ style (//) comment lines.

6.5.2.2 Include a blank line above a block of comment lines containing text.

These blank lines make comments visually distinct without relying on the editor.

6.5.2.3 A blank line may optionally follow a block of comments.

This should generally indicate that the comment is for a large block of code. No blank line implies that the comment is for the next few lines of code.

6.5.2.4 Comments are allowed on the parameters of a function call.

These comments provide supplemental information about the parameters for that specific function call. The information in parameter comments should not repeat the information in the descriptive text for the @param entries in the special documentation block describing the function. Function call parameter comments are never Doxygen comments.

Status = TestString (
           String,     // Comment for first parameter
           Index + 3,  // Comment for second parameter
           &Value      // Comment for third parameter
           );

6.5.2.5 Indent the comments with the code.

This indentation conveys the scope of the comment, as well as maintaining readability of the code.

/// Do nothing, carefully.
void
NoFun (VOID)
{
  // Only process data if mTest is TRUE.
  // This comment block applies to the entire if/else statement.
  if (mTest) {
    // This is an example comment to explain why this behavior
    // is appropriate if mTest is true.
    // This comment block only applies when mTest is true.

    ThisIsTheCode();
  } else {
    // Explain what we do if (mTest) is false.
    // This comment block only applies when mTest is false.

    ThisIsMoreCode();
  }
}