C++ Programming/Code/Style Conventions/Comments
Comments[edit | edit source]
Comments are portions of the code ignored by the compiler which allow the user to make simple notes in the relevant areas of the source code. Comments come either in block form or as single lines.
- Single-line comments (informally, C++ style), start with
//
and continue until the end of the line. If the last character in a comment line is a\
the comment will continue in the next line. - Multi-line comments (informally, C style), start with
/*
and end with*/
.
We will now describe how a comment can be added to the source code, but not where, how, and when to comment; we will get into that later.
C style comments[edit | edit source]
If you use C style comments, try to use it like this:
Comment single line:
/*void EventLoop(); /**/
Comment multiple lines:
/*
void EventLoop();
void EventLoop();
/**/
This allows you to easily uncomment. For example:
Uncomment single line:
void EventLoop(); /**/
Uncomment multiple lines:
void EventLoop();
void EventLoop();
/**/
... by removing only the start of comment and so activating the next one, you did re-activate the commented code, because if you start a comment this way it will be valid until it finds the close of comment */
.
C++ style comments[edit | edit source]
Examples:
// This is a single one line comment
or
if (expression) // This needs a comment
{
statements;
}
else
{
statements;
}
The backslash is a continuation character and will continue the comment to the following line:
// This comment will also comment the following line \
std::cout << "This line will not print" << std::endl;
- Using comments to temporarily ignore code
Comments are also sometimes used to enclose code that we temporarily want the compiler to ignore. This can be useful in finding errors in the program. If a program does not give the desired result, it might be possible to track which particular statement contains the error by commenting out code.
- Example with C style comments
/* This is a single line comment */
or
/*
This is a multiple line comment
*/
- C and C++ style
Combining multi-line comments (/* */
) with c++ comments (//
) to comment out multiple lines of code:
Commenting out the code:
/*
void EventLoop();
void EventLoop();
void EventLoop();
void EventLoop();
void EventLoop();
//*/
uncommenting the code chunk
//*
void EventLoop();
void EventLoop();
void EventLoop();
void EventLoop();
void EventLoop();
//*/
This works because a //*
is still a c++ comment. And //*/
acts as a c++ comment and a multi-line comment terminator. However this doesn't work if there are any multi-line comments are used for function descriptions.
- Note on doing it with preprocessor statements
Another way (considered bad practice) is to selectively enable disable sections of code:
#if(0) // Change this to 1 to uncomments.
void EventLoop();
#endif
this is considered a bad practice because the code often becomes illegible when several #if's are mixed, if you use them don't forget to add a comment at the #endif saying what #if it correspond
#if (FEATURE_1 == 1)
do_something;
#endif //FEATURE_1 == 1
you can prevent illegibility by using inline functions (often considered better than macros for legibility with no performance cost) containing only 2 sections in #if #else #endif
inline do_test()
{
#if (Feature_1 == 1)
do_something
#endif //FEATURE_1 == 1
}
and call
do_test();
in the program