TLDR: watch the YouTube video instead
Code comments can be a valuable tool for developers, helping to enhance the understanding and maintainability of software projects. However, knowing when to comment your code and when to refrain from doing so is equally important. In this article, we will explore the scenarios where code comments can be beneficial and the situations where they may not be necessary.
When to Comment Your Code
Follow conventions
Commenting your code becomes essential when it comes to adhering to coding conventions. Conventions define the agreed-upon standards for formatting, style, and structure within a codebase. If your code deviates from these conventions for a specific reason, commenting can help explain the rationale behind the departure.
In addition, some projects and companies prefer to their comment code, so if you’re contributing to their code, it’s important to follow the project or company conventions.
Create documentation
Code comments are an excellent way to provide supplementary documentation for your codebase. They can explain the purpose and usage of certain functions, classes, or modules, making it easier for other developers to understand and utilize your code. Documentation comments are especially valuable when working on collaborative projects or when sharing code with others.
Explain business rules, design decisions, or “the why”
In complex software systems, there are often business rules and design decisions that may not be immediately evident from the code alone. Comments can help explain the reasoning behind these choices, providing valuable context for future developers who may need to modify or extend the codebase. Including comments that clarify the “why” behind certain code sections can save time and reduce confusion in the long run.
When Not to Comment Your Code
When it goes against convention
While commenting can be helpful for deviations from coding conventions, or is the preference for a project or at a company, it’s essential to evaluate whether the deviation truly warrants an explanation. If the unconventional code is easily understandable or follows an alternative best practice, commenting might not be necessary and could clutter the codebase unnecessarily.
When it explains what the code does
Ideally, your code should be self-explanatory through its structure, variable naming, and overall readability. In such cases, adding comments that merely reiterate what the code is doing can be redundant and add clutter. Instead, focus on writing clean and concise code that is easily understood by others without the need for comments.
When you could refactor your code to be more understandable
In some cases, rather than relying on comments, it may be more beneficial to refactor your code to improve its clarity and readability. By restructuring the code, breaking it into smaller functions or modules, and utilizing descriptive variable or function names, you can make your code more self-explanatory. This approach not only reduces the need for excessive comments but also enhances the overall maintainability and comprehensibility of the codebase.
Conclusion
Commenting code can be a valuable practice when done judiciously and in the appropriate situations. Following coding conventions, creating documentation, and explaining business rules and design decisions are all valid reasons to include comments in your code. However, it’s equally important to avoid unnecessary comments when they merely duplicate what the code already expresses or when they can be replaced by refactoring the code for improved readability.
