The Importance and Examples of Comments in Code

Comments are a crucial part of coding, serving various purposes that range from explaining complex logic to temporarily disabling code blocks. They play a vital role in making code readable, understandable, and maintainable. Code comments can be used to explain the purpose of each variable, the logic behind a calculation, the modifications made to a function, and the overall function of a block of code.

Functions of Comments in Code

Explaining the Purpose of Variables: When declaring variables, comments can provide insights into their intended use. For example, comments can explain why a variable is named a certain way or what it represents. Clarifying Complex Logic: Comments can break down complex calculations or logic, detailing the steps involved and the rationale behind each action. Maintaining Functionality Records: Comments can include information about who wrote a particular function and when it was last modified. This is useful for tracking changes and understanding the evolution of the code. Explain Functionality: Comments can provide a brief explanation of the purpose of each function, making it easier for others to understand its role in the codebase. Organizing Code: Comments can divide code into logical blocks, each with a brief description of its purpose. This structured approach makes the code more readable and manageable. Temporarily Disabling Code: Comments can be used to temporarily disable parts of the code for testing or debugging purposes, and even sometimes for permanent removal of unnecessary code.

Real-World Examples of Useful Comments

During my tenure at a large multinational company, I witnessed two notable exceptions where commenting out code was allowed without issue during a code review. These exceptions were driven by the necessity of detailed explanations within the comments.

Two Reasonable Exceptions

1. Complex Formula Comments: When a code segment originates from a complex formula, comments can direct developers to external documentation or resources for a deeper understanding. For example, a comment might read: This code comes from a very complex formula. Go see [wiki link] to understand how it works.

2. External Data Structure Comments: Sometimes, code uses external data structures whose implementation is not visible within the codebase. In such cases, comments can provide insights into how to access these data structures. An example might be: This code uses some external data structure we need here and cannot see its implementation/data. It uses this and that on that index, so if you want to access it here is where you need to look.

While these examples highlight two reasonable exceptions, the overarching rule is to write code in a self-explanatory manner to minimize the need for comments. Modifying code while simultaneously making comments obsolete can lead to misleading or out-of-date information.

Personal Experience and Tips

I have a personal delusion of writing exceptionally nice comments, which stems from being thanked for my comments more than once. In my experience, the most useful comments often relate to logic. At a large multinational company, I worked on a complex module that involved detailed logic for dispatching goods. We implemented an undo feature that could be somewhat counter-intuitive, so I placed a strategic comment to explain the specific reasoning behind a potentially misleading code segment that could look like a copy/paste mistake.

Other times, logic comments are simply there to explain the process and guide developers through the code. By providing a clear flow of logic, comments help facilitate debugging and code comprehension.