Effective Comments and JavaDoc

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

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

Commenting for Documentation using JavaDoc

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

1. Check the header file
2. Use intellisense / code completion

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

Intellisense is going to find our public variables and functions, and let us know what arguments they expect.

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

1bool TakeDamage(float Percent);
2

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 improve intellisense and our documentation further by adding comments to our header file. By adding a simple comment above the method signature, our code can be described in plain english.

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

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

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 maximum health.
3 * @param Percent - The percentage of the character's maximum health to inflict as damage
4 * @return Whether or not the damage was lethal
5 */
6bool TakeDamage(float Percent);
7

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

This style of comment is called JavaDoc. It features many more properties than those demonstrated here. JavaDoc comments can include things like 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

And much more.

When we create comments in a specific manner, it 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.

Sometimes we want to write comments above lines of code, but to not have those comments be interpreted as anything more than a simple comment.

Typically, a comment that uses three slashes - /// - will not appear in our editor tooltips.

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

Commenting for Clarity

Another situation where we should consider adding comments is if our implementation is complex, or "unusual". If we think another developer will struggle to understand why a section of code was set up in a specif way, it can be helpful to add comments to it:

1void TrackEvent(Event& Event) {
2  // This event type crashes our analytics service
3  // Temporarily ignoring it while we investigate
4  if (Event.Type == EventTypes::StartLevel) {
5    return;
6  }
7
8  Send(Event);
9}
10

Another good place to add comments is to code that is simply too complex for most people to understand. An explanatory comment, often with a link to provide more information, can be very helpful.

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

Self-Documenting Code: Avoiding the need for 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 readable, rather than having messy code and explanatory comments.

If code is complex or messy, our first instinct should be to refactor it rather than explain it with comments.

This goal is sometimes referred to as creating self documenting code.

Self documenting code has at least two advantages over comments:

• Comments can fall out of date. Often people will update code and forget to update the associated comments.
• The process of refactoring code to be "self documenting" almost always improves the code to make it more maintainable.

The rest of this section outlines the 3 most common ways we can replace comments with simply better code.

Avoiding Comments by Renaming or Adding Variables

Often, a comment that describes what a variable does can be replaced by simply improving the variable name. Before:

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

After:

1int AggressionLevel { 0 };
2

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");
6

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);
6

Avoiding Comments by Introducing Meaningful 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.

Instead of needing comments to document that, we can often use new types. Before:

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

After:

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

Enum types are often useful for this purpose, too. Before:

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

After:

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

Where an existing type does not exactly match our requirements, we may be tempted to reuse 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();
4

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

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

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 that have already been learned
2std::vector<Ability> GetAbilities();
3

Instead, we can just do this with a type alias:

1using LearnedAbilities = std::vector<Ability>;
2LearnedAbilities GetAbilities();
3

Avoiding Comments by Decomposing Problems

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.

That might look something like this:

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

Instead, we should first check if the complexity can be reduced, typically by decomposing it into separate functions.

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

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

For the above function, decomposing it into smaller functions might look something like this:

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