The Dark Side of Commenting

Table of Contents

1. Introduction
2. Pros and Cons of Writing Comments in Code
   • Pros
   • Cons
3. Simplifying Code with Constants and Variables
4. Using Types to Replace Comments
   • Unique Pointers in C++
   • Optional Values
5. Problems with Comments and Benefits of Code Documentation
6. Writing High-Quality Documentation
7. Keeping Documentation in Sync with Code
8. Cases Where Comments are Still Necessary
9. The Power of Code in Expressing Intent
10. Conclusion

Pros and Cons of Writing Comments in Code

Comments play a significant role in code development, as they provide additional context and explanations for the code written. However, there are both pros and cons associated with writing comments in code.

Pros:

1. Clarity and Understanding: Comments can help programmers understand the purpose and functionality of complex sections of code.
2. Documentation: Comments can serve as documentation for developers, providing insights into the design choices and logic behind the code.
3. Collaboration: Comments facilitate collaboration among team members by guiding them through the codebase and promoting shared understanding.
4. Memory Aid: Comments can serve as reminders for specific aspects or variables within the code, helping developers keep track of different components.
5. Debugging Assistance: Well-placed comments can aid in debugging by indicating the expected behavior and intent of certain code segments.

Cons:

1. Code Decay: Frequently, comments become outdated as the code evolves, which can lead to confusion or misinformation for developers who rely on them.
2. Redundancy: When the code is self-explanatory, comments can become redundant, cluttering the codebase and distracting from the actual logic.
3. Maintenance Burden: Maintaining comments requires effort, especially if they are scattered throughout the codebase and need to be updated alongside code changes.
4. Misleading Information: Misleading comments can misguide developers, potentially leading to misconceptions and bugs.
5. Dependency on Human Effort: Unlike automated checks and tests for code correctness, comments rely solely on human effort and can be easily overlooked or neglected.

Considering these pros and cons, it's essential to strike a balance when it comes to writing comments. While they can be valuable in certain situations, alternative approaches should be considered to make the code more self-explanatory and less dependent on comments.

Simplifying Code with Constants and Variables

One effective way to reduce the need for comments is by simplifying complex code sections through the use of constants and variables. Rather than relying on comments to explain the purpose of a specific value or expression, assigning them to clearly named constants or variables improves code readability and understanding.

For example, instead of writing:

# We expect the value to be 5
if x + y * z - w > 10:
    # Do something

We can rewrite it as:

EXPECTED_VALUE = 5

if x + y * z - w > EXPECTED_VALUE:
    # Do something

By using constants or variables, the code becomes more self-explanatory, reducing the reliance on comments to convey the intended behavior.

Additionally, breaking down complex conditions into smaller parts using variables can further enhance code clarity. Instead of leaving an intricate condition with a comment explaining its purpose, we can assign meaningful names to each part and make the condition more readable:

# Complex condition
if a > b and c < d or e == f:
    # Do something

Becomes:

is_condition_satisfied = a > b and c < d or e == f

if is_condition_satisfied:
    # Do something

This approach makes the code more self-explanatory and eliminates the need for explanatory comments.

Using Types to Replace Comments

In certain cases, the use of specific data types can make comments redundant by explicitly conveying important information about ownership, validity, or optional values.

In languages like C++, the introduction of unique_ptr provides a clear indication of ownership. Instead of relying on comments to explain the responsibility of memory release, the type itself signifies that the object's ownership is transferred to the current scope. This eliminates the need for comments and ensures safer memory management without human error.

// Without unique_ptr
Thing* getThing();

// With unique_ptr
std::unique_ptr<Thing> getThing();

Similarly, when a function returns an optional value, it's better to use a data type that represents the possibility of absence rather than relying on comments to communicate this. By returning an optional type, such as std::optional in C++, developers can immediately identify that the returned value may or may not exist, preventing potential bugs caused by misunderstandings.

// Using comments to explain optional return value
// -1 means no value is returned
int getValue();

// Using an optional return type
std::optional<int> getValue();

By utilizing appropriate data types, we can minimize the need for comments and provide more explicit information within the code itself.

Problems with Comments and Benefits of Code Documentation

While comments can be useful in some scenarios, they possess inherent drawbacks that make them less favorable when compared to high-quality code documentation.

One of the main issues with comments is that they often become outdated as the codebase evolves. Developers may overlook updating comments when making changes to the code, leading to a mismatch between the comments and the actual functionality of the code. On the other hand, code documentation is less prone to decay since it typically focuses on the higher-level design and public APIs, which tend to remain stable over time.

Moreover, comments lack the infrastructure for automated checks and tests available for code. While code undergoes rigorous testing and quality checks, comments are often left unverified for accuracy, making them more prone to errors or inconsistencies. Proper documentation, on the other hand, can be reviewed, validated, and maintained alongside the code, providing reliable information to developers.

Additionally, comments are internal to the code and primarily serve developers working with the codebase, whereas code documentation is designed to cater to a broader audience, including future maintainers, external contributors, or users of the code or APIs. Well-written documentation provides clear instructions, expectations, and explanations to these different stakeholders, making it an invaluable asset for the long-term success of a project.

Considering these drawbacks and benefits, a shift towards prioritizing code documentation over excessive reliance on comments can lead to more robust, accurate, and accessible information for everyone involved in the development and maintenance process.

Continued below...