If Code Is Self-Documenting, Why Do Comments Exist?

August 3, 2022 Software Architecture • Software Development Career Advice

14:23

Explore the balance between self-documenting code and comments in programming, and discover the best practices for clear, maintainable code.

Watch or listen to this episode

In the programming world, there’s a longstanding debate between the proponents of self-documenting code and those who advocate for comprehensive commenting. While self-documenting code aims for clarity through well-named variables and straightforward logic, comments offer explicit explanations and insights into the code’s purpose and functionality.

The Evolution of Code Commenting Practices

Years ago, adding comments to code was a standard practice, especially in languages like C++ and Java. Tools even existed to ensure comments were added to every method. However, as programming evolved, a shift occurred, particularly in the consulting realm, where the focus was more on delivering features than on commenting code. This shift gave rise to the concept of self-documenting code, which posits that well-written code should be clear enough on its own, rendering comments unnecessary.

Why Self-Documenting Code Gained Popularity

Several reasons contribute to the popularity of self-documenting code:

• Laziness: Writing comments requires extra effort, and the notion of a ‘lazy programmer’ being a good programmer has been misconstrued to justify the lack of comments.
• Visual Clutter: Comments add more lines to the code, potentially making it harder to read.
• Refactoring Burden: Updating comments alongside code changes can be seen as additional, unnecessary work.
• Overconfidence in Simplicity: Programmers often overestimate the readability of their code, assuming that their naming conventions and structures are self-explanatory.

The Value of Comments in Code

Despite the arguments for self-documenting code, comments in code have several undeniable benefits:

• Reduce Comprehension Effort: Well-placed comments can significantly speed up the process of understanding code, especially for new team members or when revisiting older code.
• Accelerate Business Understanding: Comments can bridge the gap between code and business logic, explaining how the code aligns with business requirements.
• Leverage Editor Features: Modern IDEs and editors can display comments in useful ways, enhancing the coding experience without the need to dive deep into the code.
• Surface Code Behavior: Comments can clarify how code behaves under different conditions, reducing the need for extensive code analysis.
• Additional Documentation Opportunities: Tools that generate documentation from code can utilize comments to create more comprehensive and useful documentation.
• Treat Code Like a Product: Comments encourage a mindset of treating code as a product that needs to be user-friendly, not just for end-users but for other developers as well.

Conclusion: A Balanced Approach

The key to effective coding isn’t about choosing between self-documenting code and comments; it’s about finding the right balance. Well-named variables and clear logic are crucial, but they don’t always provide the full context or explain the ‘why’ behind the code. Thoughtful comments can fill these gaps, making the code more accessible and maintainable. As a programmer, you should aim to write code that is as clear as possible on its own while also recognizing the value that well-placed comments can add.

About the Healthy Software Developer show.

On the show, Jayme shares all of his teamwork and leadership strategies, guidelines for healthy company culture, and stories about real projects so you can have a sustainable career in the software industry.

Develop a mindset and habits to keep you calm so you still love writing code - avoiding the traps most developers fall into.

Subscribe Now

YOUR HOST

Jayme Edwards

A family man and veteran of over 30 software projects, Jayme experienced many wins and losses that led him to helping developers succeed in their careers online.