02 - comments

Backslash at the end of line

Watch out for accidental \ at the end of a line. It extends it to the next one, even in the case of single-line comments:

1
2

// text... \
this text is also a part of the comment

It's advised to just write 2 comments instead (or 1 multi-line):

1
2

// text...
// text...

Documentation comments

Some tools may automatically help writing pretty comments like this:

1
2
3
4
5
6
7
8
9

/**
 * @brief some short description
 * @param x parameter x descritption
 * @param y parameter y descritption
 * @return result description
 *
 * @details long description, usually
 * describing preconditions and error cases
 */

By convention, multi-line comments beginning with /** and single-line comments beginning with /// are comments for code-analyzing tools. Compilers ignore text inside comments, but some tools expect certain syntax inside them - e.g. tags denoted with @ are searched by documentation tools like Doxygen which generate documentation from code. Some IDEs may also display help boxes by relying on these tags.

The purpose of comments

In ordinary code the main purpose of comments is documentation and explaining why something is done, not how. Very often there are many ways to do certain task. The code describes how to do this task. But why this particular way? This should be written in the comment.

Example, bad:

1
2
3
4

if (bargain_percent >= 100)
	price = 0; // set price to 0 when bargain exceeds 100%
else
	price = price - price * bargain_percent / 100;

Example, good:

1
2
3
4

if (bargain_percent >= 100)
	price = 0; // prevent price reduction below 0
else
	price = price - price * bargain_percent / 100;

In the example above the comment should not explain math (reducing amount by percents is pretty straightforward) but why there is a special case for bargains exceeding 100% - in such cases the player could abuse the game by reducing price to negative numbers, potentially ending up earning money while buying the item.

In professional code comments should not explain code as we should assume the reader is already familiar with the language. It's more important to document why a specific block of code exists and why a particular solution was choosen. Once you start making bigger projects or work with other people you will realize how unlikely it is that someone will remember all of "the obvious things" in the program that has multiple thousand lines of code.

In the tutorial this rule will obviously be violated as the goal here is to teach you programming. Very likely you will also make some notes with explanatory comments. Just be aware that in the actual job the purpose of comments is much different.

Formatting

A battle almost as old as deciding which side toiler paper should go on is code formatting, especially braces ({}).

Below I present 2 most common formatting styles found in C and any other language based on C's grammar (such as C++, Java, JavaScript, C#):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// Allman
if (condition)
{
	do_this();
}
else
{
	do_that();
}

// K&R - Stroustrup variant
if (condition) {
	do_this();
}
else { // some variants would write "} else {"
	do_that();
}

A much larger list can be found on https://en.wikipedia.org/wiki/Indentation_style.

For beginners, Allman will usually be better as with it it's easier to reason about indented code. K&R main advantage is more concise code, allowing to fit more on fewer lines. Not every brace in K&R is placed on the same line - function-opening brace is placed on the next. IDEs may also feature automatic code formatting tools.

A different issue is maximum allowed line length. There is no technical limit, but most people break long lines once they become too long - vertical scrolling is fine but hardly anyone likes horizontal scrolling. Sticking to a line length limit lets people open multiple editors side by side. Recommendations vary. In the past it was 80, partially due to technical reasons but now it's not rare to find projects with maximum 120 or 150 characters in line.

If you happen to split a line, it's recommended to align the code (similarly how you can find aligned comments in the tutorial lessons) and place the operator on the next line - if expression like 2 * 3 + 4 * 5 is split over +, the + character should be first on the next line, not last on the previous line (this increases readability).

A well-formatted program is easier to understand. This is hilariously explained in CppCon 2018: James McNellis "The Shape of a Program".

The presentation mentions some simple refactorings (e.g. extracting if statements to unindent nested code) which will be covered in detail in later lessons. There are many simple code transformations you can apply to reduce code complexity; some IDEs even detect such cases and propose automatic refactorings.