Effective Comments and Javadoc

We have previously looked at how we can add comments to our code using // and /* */.

1class Character {
2 public:
3  // This is a single-line comment
4  int GetHealth() { return mHealth; }
5
6 private:
7  /* This comment can span
8  * multiple lines
9  */
10  int mHealth;
11};

Whilst knowing how to comment is useful, there is a more nuanced topic, around knowing when to comment.

Commenting for Future Work

Often when we’re writing a class or function, we want our code to do something that is not currently possible.

Perhaps the functionality is being worked on by a colleague and they’re not done yet, or it’s just something we know we’ll need in the future, but don’t want to work on just yet.

In those scenarios, it’s common to leave a comment in our code, noting where this integration will happen:

1// TODO: send event data to the analytics
2// service once it is ready
3void TrackEvent(Event& Event) {}

By convention, we prepend TODO or NYI (not yet implemented) to these comments. This means that, before we release, we can do a project-wide text search for TODO to determine if anything is outstanding.

Some tools interact with comments in this style too - for example, the Visual Studio Task List (available from the View menu) presents all of the TODO comments in our project.

Comments to Explain Complexity

Another good place to add comments is to code that is simply too complex to understand. Our first instinct should be to determine if we can reduce the complexity - we provide some examples of that later in the lesson.

But in some scenarios, reducing the complexity is not desirable as it would reduce performance, in a function where performance is very important.

In these contexts, an explanatory comment, often with a link to provide more information, can be very helpful:

1// This is an implementation of the Fast
2// Inverse Square Root algorithm - see:
3// wikipedia.org/wiki/Fast_inverse_square_root
4float InvSqrt(float x) {
5  using std::bit_cast, std::uint32_t;
6
7  const float y { bit_cast<float>(
8    0x5f3759df - (bit_cast<uint32_t>(x) >> 1)
9  )};
10  return y * (1.5f - (x * 0.5f * y * y));
11}

Commenting to Give Context

Often, comments are used to explain what complex code is doing, but that is rarely necessary. Anyone who needs to understand what code is doing can take the time to analyze it.

It’s often more useful to explain why code is doing something, as that information isn’t as easy to regenerate.

Often, we have to do unusual things in our code that may be confusing to anyone reading it in the future. They’ll understand what our code is doing, but not why.

When this happens, it can be helpful to add a comment to explain:

1void TrackEvent(Event& Event) {
2  // We redact user email addresses to
3  // protect personal data and privacy
4  Event.User.Email = "";
5
6  SendToAnalytics(Event);
7}

Comments as Documentation

When other developers (or ourselves, in the future) want to get an idea of what classes can do, we're generally going to explore in one of two ways:

1. Check the header file
2. Use IDE features, such as tooltips and autocomplete

We can infer quite a lot in this way. The header files are going to list all the functions and their method signatures.

When we’re using an IDE, the UI is typically going to find the public variables and functions of the class we’re using and provide some information. By looking at the function name, we can hopefully get an idea of what the function does. Similarly, by looking at the parameter types and names, we can usually get an idea of what arguments we need to provide.

The following screenshot is an example of this from Visual Studio, which calls this feature IntelliSense.

This is useful, but sometimes won't have all the information we might need. Let's look at this function, for example:

1bool TakeDamage(float Percent);

What is the bool that this function returns? And what is the Percent parameter? Is it the percentage of the character's maximum health? Or current health? Or something else?

We can further improve IntelliSense and our documentation by adding comments to our header file. By adding a simple comment above the method signature, our code can be described in plain language:

1/* Take a percentage of the character's 
2  * maximum health as damage.  Returns
3  * true if the damage was Lethal
4 */
5 bool TakeDamage(float Percent){};

Most IDEs will also show this comment when we use our classes, or hover over calls to our function:

Structured Comments and Javadoc

Comments can be even more powerful when we follow a specific pattern. If we format our comments in a structured style, other systems will be able to read and understand our comments at a programmatic level.

Take this style of commenting, for example:

1/**
2 * Take damage based on the character's
3maximum health.
4 * @param Percent - The percentage of the
5 * character's max health to inflict as damage
6 * @return Whether or not the damage was lethal
7 */
8bool TakeDamage(float Percent);

If we now view our tooltip in our editor, it is likely to have been formatted in a more structured way.

These are called Javadoc-style comments, which were popularised by a documentation generator created for the Java programming language. It features many more properties than those demonstrated here. Javadoc comments can include things like:

• links to websites
• references to other blocks of code
• flags to inform users that the function is deprecated and they should probably use something else

When we create comments in a specific manner, they can be read and understood not just by humans, but also by other tools. As we've seen, this includes our IDE, but there are many more use cases.

For example, Doxygen can use comments written in this style to automatically create documentation websites for our projects.

1/// This comment will not appear in tooltips
2int Number { 4 };

The Problem with Comments

Whilst comments are often useful, they can often be misused as a way to mitigate messy code.

Ideally, our code should require as few comments as possible. We should strive to make our code as simple as possible, rather than having complex code and explanatory comments.

If code is confusing, our first instinct should be to determine if we can make it less confusing, rather than explain it with comments.

Code that strives to be as understandable to humans as possible, without needing additional comments or documentation, is sometimes referred to as self-documenting code.

Making our code clearer has several advantages over using comments to explain complex code. The two main advantages are:

• Code is the real "source of truth". Comments are ignored by the compiler, so can be misleading/wrong. This often happens as a result of future code changes, that neglect to also update the associated comments
• The process of refactoring code to be "self-documenting" almost always improves it, making future work easier.

The rest of this section outlines the four most common ways to replace comments with better code.

1. Removing Unnecessary Comments

Another common misuse of comments is those that simply explain what the code is doing. These are unnecessary and simply add noise and maintenance overhead:

1int Add(int x, int y) {
2  // Return the result of adding x and y
3  return x + y;
4}

2. Renaming or Adding Variables

Often, a comment that describes what a variable does can be replaced by simply improving the variable name. We can improve the following code:

1// The aggression level
2int Level { 0 };

We just need to use a more descriptive variable name:

1int AggressionLevel { 0 };

Additionally, we often have literals in our code that warrant an explanatory comment. These literals are sometimes called "magic strings" or "magic numbers" - seemingly arbitrary values that have some special properties.

1// Unicode character for a smiling emoji
2Chat.Send("U+1F600");
3
4// This URL returns our special offers
5HTTP::Get("https://192.63.27.92");

We can make that relationship concrete and self-documenting by just creating variables.

1string SmilingEmoji { "U+1F600" };
2Chat.Send(SmilingEmoji);
3
4string SpecialOffers { "https://192.63.27.92" };
5HTTP::Get(SpecialOffers);

3. Introducing Descriptive Types or Aliases

Another common source of comments is documenting properties associated with types. We might have a variable or a set of variables that have some semantic meaning that is not immediately clear. Below, we have three floats, and their relationship is established just through a comment

1// x, y, and z positions in the world
2float x { 0 };
3float y { 0 };
4float z { 0 };

Instead, we can introduce a new type that makes that relationship concrete:

1struct Position { float x; float y; float z; }
2
3Position WorldPosition { 0, 0, 0 };

Enum types are often useful for this purpose, too. Below, we have an int type where the values have some hidden meaning, which we’ve documented in a comment:

1// 0 is friendly, 1 is neutral, 2 is hostile
2int AggressionLevel { 0 };

Instead, we should add an enum type to handle this:

1enum class Aggression {
2  Friendly, Neutral, Hostile };
3auto AggressionLevel{Aggression::Friendly};

Where an existing type does not exactly match our requirements but comes close, we may be tempted to use it with some comments:

1// Returns ability damage as a std::pair
2// first is damage, second is crit chance
3std::pair<int, float> GetDamageValues();

Instead, we should consider just introducing a new, self-documenting type:

1struct AbilityDamage {
2  int Damage; float CritChance;
3};
4
5AbilityDamage GetDamageValues();

Even if a more generic type does match our requirements, we sometimes feel a comment is warranted to specifically explain what that type contains:

1// This vector only contains the abilities
2// that have already been learned
3std::vector<Ability> SpellBook;

Instead, we can do this with a type alias:

1using LearnedAbilities = std::vector<Ability>;
2LearnedAbilities SpellBook;

4. Decomposing Problems using Helper Functions

When we create a complex function, composed of multiple parts, our first instinct is often to describe what is going on in that function by introducing a lot of comments.

Let's imagine we have a complex member function that looks something like this:

1class Character {
2 public:
3  bool Attack(Character* Target) {
4    // Make sure we have a target, and it is
5    // valid to attack it
6    if (!Target) return false;
7    if (Target.Hostility == Friendly) {
8      return false;
9    }
10
11    // Target is attackable, but we need to make
12    // sure it is in range
13    float[x1, y1, z1] = MyPosition;
14    float[x2, y2, z2] = Target->Position;
15    float x = x1 - x2;
16    float y = y1 - y2;
17    float z = z1 - z2;
18
19    // The square root of this values will be
20    // the distance
21    float Distance{(x * x) + (y * y) + (z * z)};
22
23    if (sqrt(Distance) <= 10) {
24      // Attack was successful
25      Target->TakeDamage();
26      return true;
27    }
28    // Attack was unsuccessful
29    return false;
30  }
31};

Breaking a big problem into smaller functions makes our code simpler, and allows us to replace our comments with descriptive function names instead.

A function that does part of the computation of another function is sometimes referred to as a helper function.

As an additional benefit, quite often these smaller, more generic functions can be useful in multiple places. This can make future work easier, by reducing the amount of code we have to write and maintain.

For the above function, we can simplify it by introducing two helper functions - isValidTarget() and GetDistance():

1class Character {
2 public:
3  bool Attack(Character* Target) {
4    if (!isValidTarget(Target)) return false;
5
6    Target->TakeDamage();
7    return true;
8  }
9
10 // ... other public members
11
12 private:
13  bool isValidTarget(const Character* Target) {
14    if (!Target) return false;
15    if (Target.Hostility == Friendly) {
16      return false;
17    }
18
19    return GetDistance(Target->Position) > 10)
20  }
21
22  float GetDistance(Position TargetPosition) {
23    float[x1, y1, z1] = MyPosition;
24    float[x2, y2, z2] = TargetPosition;
25    float x = x1 - x2;
26    float y = y1 - y2;
27    float z = z1 - z2;
28
29    return sqrt((x * x) + (y * y) + (z * z));
30  }
31
32  // ... other private members
33};

Summary

This lesson provides an introduction to effective commenting and documentation. We covered:

• Types of Comments: Reviewing single-line (//) and multi-line (/* */) comments.
• Purposeful Commenting: Learning when and how to comment, including using comments for future work (TODO, NYI) and explaining complex code.
• Contextual Comments: Emphasizing the importance of comments that give context and explain the 'why' behind code decisions.
• Javadoc and Documentation: Introducing structured commenting styles like Javadoc for better documentation and tool integration.
• Self-documenting Code: Strategies for writing code that is self-explanatory, reducing the reliance on external comments.

Preview of the Next Lesson

In the next lesson, we'll dive into the world of coding standards and how they enhance the readability and maintainability of code. We'll explore the role of style guides in programming and introduce ClangFormat, a powerful tool for automatically formatting our files.

Key Topics:

• Understanding how style guides are used to create consistent programming practices in team environments.
• Introduction to ClangFormat for automatic code formatting.
• Setting up and configuring ClangFormat in your development environment.
• Examples of common style guides and how to use them in ClangFormat.

Next Lesson

Automatic Code Formatting

This lesson introduces the concept of Style Guides and ClangFormat, focusing on how to achieve consistency in our code

ContinueView Course