Comments
In general comments are considered to be helpful. However, poorly written comments can make the source code harder to understand and more difficult to maintain. These guidelines aim to ensure that comments improve comprehension and minimize the maintenance of comments in source code.
Module comments
Include the module comment in the source file. The purpose of the module comment is to describe the intent of the module. To reduce maintenance, do not update the module comment to document modification, unless the intent of the module changes. Handle general change control documentation in the source control system.
Example of a typical module comment:
/* Commands.cpp : Implementation of CCommands. This class
implements the commands collection
Created By: John Smith, 21/03/2017 */
Method comments
Unless the intent of a method is obvious, always provide a comment. If the method is part of a COM interface, put the comment in the Interface Description Language (IDL) file. For example:
/* Description:
Returns a pointer to the data store
*/
[propget, id(43), helpstring("property DataSource")]
HRESULT DataSource([out, retval]
IDataSource* *pVal);
If the method is a class function, put the comment in the source file, after the first function brace. For example:
void CCommands::FinalRelease()
{
// Release the command interfaces held in the collection
The purpose of method parameters should be evident from the parameter names. When necessary, explain what parameters are used for in the method comment. However, because of the overhead of writing and maintaining parameter comments, only do this when necessary for understanding the method.
Make sure that you add the intent of the method return values to the method comment. For example, a method returning a Boolean to indicate success, should contain a comment such as Returns true if successful, otherwise returns false.
Source paragraph comments
Use comments to explain the purpose of a section of code. The comment should not be a repeat of the code, but should describe the intention of the block. For example:
// Compute the square root using Newton-Raphson method
dSqrRoot = dValue / 2;
while ...
Marker comments
Use the Microsoft TODO convention to mark incomplete code. This makes it possible to search the source for any work in progress. For example,
// TODO: add code to initialize document
Separation comments
Use a comment line after the module comments block and between methods in a module. For example,
/* Commands.cpp : Implementation of a fictitious class that
does nothing in particular.
Created By: John Smith, 02/07/2017 */
// -------------------------------------------------------
void CMyClass::Init()
{
// TODO: Initialize class
}
// -------------------------------------------------------
void CMyClass::Open(LPCTSTR *pszConnection)
{
...
See also