Why You Should Minimize Comments for Cleaner Code as a Developer
Written on
Chapter 1: The Misconception About Comments
In my earlier days as a developer, I believed that writing extensive comments was a hallmark of good coding practice. However, after engaging with Robert C. Martin's insightful book, Clean Code, I came to understand that I had been misapplying comments.
One fundamental lesson is to minimize the use of comments and instead clarify your intentions through your code.
Comments can mislead, whereas code remains truthful.
While comments are intended to elucidate the function of the code, poorly constructed comments can propagate misunderstandings. Consider these issues:
- Inaccurate Explanations: Comments may fail to accurately describe the code's purpose, leading to confusion and misinterpretation.
- Stale Information: When a function's behavior changes, comments often remain unchanged, rendering them misleading.
Code is self-explanatory. Although it may sometimes be complex, it will always reflect its true purpose. Therefore, it is essential to adopt clear naming conventions and formatting to enhance readability.
Section 1.1: Examples of Code Clarity
Consider the following code snippets:
Poorly Written Code:
// Function receives a list of albums and an artist. It then loops through the list of albums and returns a list of albums which have the same artist
private function loopFunction($items, $artist)
{
$artists = [];
foreach($items as $item) {
if($item['artist'] === $artist) {
array_push($artists, $artist);}
}
return $artists;
}
The code is ambiguous due to unclear naming, lack of type declarations, and absence of a return type, necessitating a comment for explanation.
Improved Code:
private function findAllAlbumsFromArtist(array $arrayOfAlbums, string $artist): array
{
$arrayOfAlbumsFromArtist = [];
foreach($arrayOfAlbums as $album) {
if($album['artist'] === $artist) {
array_push($arrayOfAlbumsFromArtist, $artist);}
}
return $arrayOfAlbumsFromArtist;
}
This function is self-explanatory. It doesn't require a comment, as the code itself conveys its purpose.
Section 1.2: When Are Comments Necessary?
Ask yourself: Is this comment necessary because the code is unclear?
- Clarifying Intent: If you've implemented a unique solution for a specific reason, it’s acceptable to articulate your intentions through a comment.
- Enhancing Readability: In some cases, code may be too intricate to be self-explanatory. If this is true, provide a comment that succinctly describes its function, ensuring you revise it with any code changes.
- Highlighting Critical Sections: Certain parts of code may hold significant importance. A comment can help emphasize why this particular section is crucial.
// This trim function is crucial; it ensures there are no spaces in the URL.
- Explaining Outcomes: It’s helpful to inform colleagues about the potential implications of executing specific code.
// Beware: This script takes 5 hours to run.
Conclusion: Strive for Clarity
Focus on crafting quality code, and the necessity for comments will decrease. A well-placed comment can bridge knowledge gaps, but before adding one, take a moment to assess its necessity. If it’s warranted, ensure that it is both accurate and detailed enough for newcomers.
Most often, dedicating time to improving code readability will yield better results.
The first video titled "Clean Code #4 - Why Code Comments Are Bad!" discusses the pitfalls of excessive commenting and emphasizes clarity in coding practices.
The second video, "Clean Coders Hate What Happens to Your Code When You Use These Enterprise Programming Tricks," highlights common mistakes that can lead to poor code quality and the importance of clean coding principles.