Beginning C++: Comments Style Guide

Home / Beginning C++: Comments Style Guide

Beginning C++: Comments Style Guide

November 24, 2015 | Article | No Comments

Comments, believed or not, is one of important concept. It is not as crucial as logic flow in program but comment is still believed as one.

Comments are portions of the code ignored by the compiler which allow programmer to make simple notes in the relevant areas of the source code. Comments come either in block form or as single lines. It is simply ignored by compiler. But the value of comment lies as a note, a message between programmer, a reminder about piece of code, etc.

A good comment can prevent miscommunication between programmers. How can you explain your piece of code? A comment would do.

Why do I have to write a single article for just a comment? Here, in this article I want to give you a good way of writing and code. Isn’t it nice if other people can understand your code without you explain face to face by them, only by comments?. See the essential point there? Great!

Type of comments on C++

How could you write a comment on C++? There are two kinds / types: single-line and multi-line comments.

Single-line comment

A single line comment is a comment accommodated only on single line. It is start with // and continue untul the end of the line (met newline character). If the last character in a comment line is a \ the comment will be coninued in the next line.

sample:

// This is a single comment. The code below will be compiled.
void myFunction();

// This is a comment \
written in some lines. The code written below will be compiled.
void myFunction2();

void myFunction3(); // The code will be compiled, except this comment

Multi-line comment

A block of comment is consist of one to many comment at a single area. Start with /* and end with */. If you enclose code within it, the code would be part of comment. It won’t be compiled by compiler. remember to CLOSE the comment block you have start.

Sample:

/*
This is a comment
in a block
Expect it
*/
void myFunction();

/*
void myFunction2();
That function won't be compiled.
*/

void myFunction3(); /* this code would be compiled */

When and How to Comments

We have known the 2 comment types on C++. Now let’s inspect how can we use the comment? These are some nice style of commenting. I won’t force you to follow it.

  1. Write comment above or below a function to describe what it does and other characteristic (parameter / argument needed, return value, etc)
  2. If you write struct or class, write a member variable in a single line and give comment of what is it.
  3. a

There is a nice example about how we write a comment:

// This structure store value for computer register
struct Register {
int h; // This is the high bit
int l; // This is the low bit
};

/**
 * @author: Satria Ady Pradana
 *
 * Create a vector dynamically using heap allocation.
 * @pre
 *      V is not initialize
 *      size is defined and has value > 0
 *
 * @post
 *      V is created with size nodes
 *
 * @param
 *      V: a pointer
 *      size: size of list we want to create
 *
 * @return
 *      <none>
 *
 * @throw
 *     <none>
 */
void createVector(Pointer& V, int size);

A nice and sweet piece of code, right? 😀
The code is self explained with explanation for each stage. Each parameter is also documented.

,

About Author

about author

xathrya

A man who is obsessed to low level technology.

Leave a Reply

Your email address will not be published. Required fields are marked *

Social media & sharing icons powered by UltimatelySocial