This content originally appeared on Level Up Coding - Medium and was authored by Ella sheer
How a Strict No-Comments Policy Pushed Me To Be a Better Developer.
I spent four years in a workplace with a strict no-comments approach in code reviews. I was sometimes frustrated, but this also pushed me to become a better developer. Here are a couple of things I learned along the way.
I was writing comments for the right reasons but with an opposite result
I genuinely wanted to help others read my code; I thought I saved other people’s time and was a good co-worker.
But adding comments does the opposite-
Comments are less likely to be maintained
Code changes. Wrong code causes bugs, so it has to be fixed or the business will suffer. Wrong or irrelevant comments don’t have this impact and are likely to be ignored.
The disclaimer is that overlooking irrelevant errors depends on the culture at your workplace. For example, maybe your company pays very close attention to every comment.
Even so, this adds overhead, as every comment line has to be found, read, and verified during the code review process.
To sum up this part - we either ignore comments or end up working for them, instead of having them working for us.
But How can we reach the clear code goal without comments?
Naming
It’s not exactly a new concept to anyone trying to code cleaner, keeping variables, methods, and classes with clear, self-explaining names.
Breaking to chunks
With the single responsibility principle in mind, break a code piece into smaller parts. When is it time to split?
Some rules are-
- Method body should fit into a screen.
- Every four lines of code that does something probably need to go into a helper method.
- Also, always keep one class per file.
- One responsibility per class.
A real-life showcase
Let’s consider this commented code-
We understand it does some manipulations on the bandwidth, and if we read the comment we understand the need- we need to convert the units from milliseconds to micro, but only in some instances.
Now consider this self-documenting code-
It takes much more lines, for sure.
If you had to dive into the logic to fix a bug, which code allows you to understand the logic flow?
When is there no way around?
For example, if the code relates to an external API or third-party code that behaves a certain way, you may not find a workaround except adding a note, or even a link to the relevant source code.
In conclusion
Comments may be a helpful tool, but they also cause an overhead for the reader and maintainer.
Before adding a comment, ask yourself- would I improve my code instead?
No Comment (In The codebase). was originally published in Level Up Coding on Medium, where people are continuing the conversation by highlighting and responding to this story.
This content originally appeared on Level Up Coding - Medium and was authored by Ella sheer
Ella sheer | Sciencx (2021-11-17T16:40:32+00:00) No Comment (In The codebase).. Retrieved from https://www.scien.cx/2021/11/17/no-comment-in-the-codebase/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.