Replace comments with better code

Valerio Barbera

Hi, I’m Valerio, software engineer and CTO at Inspector.

Software development is collaborative by nature. If you’re working for a company, regardless of size, you’re obviously working with others.

I strongly believe in the comments as documentation for certain functions or entire classes in a way that should help developers in two way:

  • Navigate the code using comments to lead the IDE behaviour;
  • Add more contextual information to avoid misunderstanding about why that code block was designed that way (increase perofmance, resolve bug, etc…)

When you are part of a team, comments in the code can cause discussions and disagreements. Let us agree on the concept of “comments in the code”.

<?phpclass Math
{
public function calc()
{
// Add b to a
$c = $this->a + $this->b; // return the result of a + b
return $c;
}
}

This above could be the result of a meeting where the team is recommended to add comments on the code.

Repeating the code is the worst you can do, adding comments that describe what your code is doing when it would be much clearer to read the code itself means that you waste time and other developers will spend time too to investigate unless documentation.

Junior developers rely on comments to tell stories when they should rely on code to write their stories. Less experienced developers tend to use comments to describe the story behind a code block.

We can even be more expressive taking care on the names of classes, functions and variables without writing a line of comments.

If you feel the need to write comments to explain what your function is for, the first thing you need to do is consider the possibility of restructuring the code you wrote to make it explain its purpose alone. Take a look at the example below:

<?php/**
* Calculate spending limit by customer income and try to find a room above that price.
*/
public function rentRoom($income)
{
$spending = round(($income*0.15) / 12);
foreach ($this->rooms as $room) {
if ($room->price <= $spending) {
return $room;
}
}
throw new RoomNotFoundException();
}

Only one comment line could be acceptable. Or could we review the code to make it clearer, modular and avoid any comment?

<?php/**
* Rent a room based on customer's income
*
* @params integer $income
*/
public function rentRoom($income)
{
try {
$this->findRoomByPrice(
$this->calculateCustomerSpending($income)
);
} catch (\Eception $exception) {
// do something with error
}
}public function findRoomByPrice($limit)
{
foreach ($this->rooms as $room) {
if ($room->price <= $limit) {
return $room;
}
}
throw new RoomNotFoundException();
}public function calculateCustomerSpending($income, $percentage = 15)
{
return round(
($income*($percentage/100)) / 12
);
}

The code is more verbose and there is no need for comments.

The numbers now have a label and the functions have a name that clearly explains what they do. This example may seem a little excessive if taken individually. What you need to focus your attention on is the strategy, the value of explaining how and why that code is found there using the code itself.

My advice is to not underestimate this aspect. If too many comments are present in the code it increases exponentially the risk that you, and the other developers, will pay less attention to their presence also propagating in the documentation of the old and wrong information.

Very often comments are obviously needed to explain more complex scenarios or link to bugs and it is not possible to do so using only the names in the code. In modern IDE comments are often useful to improve code navigation. In any case, the next time you feel the need to write comments you can ask yourself if it is possible to have the same readability using the code itself drastically improving maintainability.

Conclusion

If you want learn more about Inspector visit our website (https://www.inspector.dev) and start monitoring your application for free in just two minutes to find out issues before your application users do.

Thank you so much for reading it. To make Inspector more sophisticated and mature, it will not be possible to accomplish without your help. Don’t hesitate to share your thoughts on the comment below or drop in live chat on our website!

Related Posts

NodeJs Real-Time Execution Monitoring with Inspector

Have you ever desired to watch your code running, instead of just imagining it? Hi, I’m Valerio software engineer from Italy and CTO at Inspector. As product owner I learned on my skin how an application issue can be so hard to fix, creating a negative impact on the users experience, or block new potential

How to accelerate application performance with smart SQL queries.

Why so many performance issues are caused by the database? We often forget that each request is not independent of other requests. If one request is slow, it’s unlikely to affect the others… right? Database is a shared resource used by all processes that runs in your application. Even just one poorly designed access can

Application performance monitoring tools – Why, when, what!

In this article I reported my experience working on large applications, and how monitoring cames in my journey when I started producing software designed to solve business critical problems. Hi, I’m Valerio, software engineer from Italy and CTO at Inspector. Solve customers critical problems can generate great business opportunities, but in these situations you need

Stop losing customers and money
due to technical problems in your applications

Monitor performance of your code execution in real-time and identify bugs and bottlenecks before your users do.
Real-Time Application Monitoring Platform.
2020 © Inspector S.R.L - VAT: 09552901218