The Importance of Commenting Your C++ Code

While comments may seem like a minor element to the many lines of code that combine to make a game, application or even an entire operating system, in actual fact they’re probably one of the most important factors.

Comments inside code are basically human readable descriptions that detail what the code is doing at that particular point. They don’t sound especially important but code without comments is one of the many frustrating areas of programming, regardless of whether you’re a professional or just starting out.

In short, all code should be commented in such a manner as to effectively describe the purpose of a line, section, or individual elements. You should get in to the habit of commenting as much as possible, by imagining that someone who doesn’t know anything about programming can pick up your code and understand what it’s going to do simply by reading your comments.

In a professional environment, comments are vital to the success of the code and ultimately, the company. In an organisation, many programmers work in teams alongside engineers, other developers, hardware analysts and so on. If you’re a part of the team that’s writing a bespoke piece of software for the company, then your comments help save a lot of time should something go wrong, and another team member has to pick up and follow the trail to pinpoint the issue.

Place yourself in the shoes of someone whose job it is to find out what’s wrong with a program. The program has in excess of 800,000 lines of code, spread across several different modules. You can soon appreciate the need for a little help from the original programmers in the form of a good comment.

The best comments are always concise and link the code logically, detailing what happens when the program hits this line or section. You don’t need to comment on every line. Something along the lines of: if x==0 doesn’t require you to comment that if x equals zero then do something; that’s going to be obvious to the reader. However, if x equalling zero is something that drastically changes the program for the user, such as, they’ve run out of lives, then it certainly needs to commented on.

Even if the code is your own, you should write comments as if you were going to publicly share it with others. This way you can return to that code and always understand what it was you did or where it was you went wrong or what worked brilliantly.

Comments are good practise and once you understand how to add a comment where needed, you soon do it as if it’s second nature.

C++ Comments

Commenting in C++ involves using a double forward slash ‘/’, or a forward slash and an asterisk, ‘/*’. You’ve already seen some brief examples but this is how they work.

Step 1 – Using the Hello World code as an example, you can easily comment on different sections of the code using the double forward slash:

//My first C++ program
cout << “Hello, world!\n”;

Step 2 – However, you can also add comments to the end of a line of code, to describe in a better way what’s going on:

cout << “Hello, world!\n”; //This line outputs the words ‘Hello, world!’. The \n denotes a new line.

Note, you don’t have to put a semicolon at the end of a comment. This is because it’s a line in the code that’s ignored by the compiler.

Step 3 – You can comment out several lines by using the forward slash and asterisk:

/* This comment can cover
several lines without the
need to add more slashes */

Just remember to finish the block comment with the opposite asterisk and forward slash.

Step 4 – Be careful when commenting, especially with block comments. It’s very easy to forget to add the closing asterisk and forward slash and thus negate any code that falls inside the comment block.

Step 5 – Obviously if you try and build and execute the code it errors out, complaining of a missing curly bracket ‘}’ to finish off the block of code. If you’ve made the error a few times, then it can be time consuming to go back and rectify. Thankfully, the colour coding in Code::Blocks helps identify comments from code.

Step 6 – If you’re using block comments, it’s good practise in C++ to add an asterisk to each new line of the comment block. This also helps you to remember to close the comment block off before continuing with the code:

/* This comment can
* cover several lines
* without the need to add more slashes */

 

Find more guides like this in…

David Hayward

David has spent most of his life tinkering with technology, from the ZX Spectrum, getting his hands on a Fujitsu VPP5000/100 supercomputer, and coding on an overheating Raspberry Pi. He's written for the likes of Micro Mart, Den of Geek, and countless retro sites and publications, covering reviews, creating code and bench testing the latest tech. He also has a huge collection of cables.

Related Articles

Back to top button