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();
}
}