Comments

Comments are used to add descriptions and explanations to the code.

Motivation

Comments help communicate the intent of complex pieces of code. Not only are they helpful for helping others understand code that you wrote, but they are also great for your future self when you look back at your old code and think "what the heck was I thinking??" You'll see them used by me in code snippets to help explain code to you! 😄

info

Comments do not affect the operation of the program in any way. They are completely ignored during compilation.

Types of comments

There are single line comments:

#include <iostream>

int main()
{
	// this is a single line comment
	// it starts with "//"
	// and ends with the end of the line
	std::cout << "Hello, World!";
}

... and multi-line comments:

#include <iostream>

int main()
{
	/*	this is a multi-line comment
		it starts with "/" followed directly by "*"
		and ends with "*" followed directly by "/"
	*/
	std::cout << "Hello, World!";
}

Good practices

Meaningful comments

When looking at code for the first time, programmers often have to sit down for several minutes and work through each step it performs. Sometimes these may be obvious steps, such as calculating Pythagorean's Theorem - it's just a few multiplications... nice, short, and easy.

But, imagine a big complicated algorithm, such as a rocket engine ignition sequence. You may see a comment block like:

🚀 IgnitionSequence.cpp

/*
	1. Engage hydraulic engine return
	2. Activate 4 igniters
	3. Open LOX valve
	4. Wait until combustion chamber threshold is reached
	5. Open main fuel valve
*/

You, as a future programmer, may look at this and understand what all of these terms mean. But why are they in this order specifically? Why do we need to "Engage the hydraulic engine return?" Why do we open the LOX valve first? Why don't we activate the igniters until after the main fuel valve is opened? Questions like these are unanswered by comments that look like the above. Just describing what things are isn't enough to explain it.

// Prints UUDDLRLRBA
std::cout << "UUDDLRLRBA";

While this comment does accurately describe what this line of code does, it doesn't help us understand why the heck we are printing a seemingly random series of characters. But consider the next version of the comment:

// Prints the Konami Code, which causes the player to get 30 extra lives in the NES game Contra
std::cout << "UUDDLRLRBA";

NOW we suddenly see why this line of code is important! We now know that this line of code was necessary for giving the player 30 extra lives in Contra! If we didn't know the Konami Code beforehand, we may have thought this code was useless and deleted it. But, now we can see that this snippet is meaningful and should not be removed.

An example of a poor comment on a cat. Perhaps a better comment would say its name and its owner.

Comment in English

It's best to use English to write comments. English is a lingua-franca for programming on the Internet. While it may not matter now right this moment, someone else may be reading your code in the future! 😃