Replace comments with better code

Comments in the code are important and I strongly believe in the comments as documentation for certain functions or entire classes.

When you are part of a team, comments in the code often cause discussion and disagreement. Let us agree on the concept of “comments in the code”.

class 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 pushed to comment carefully.

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 greater 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 this example:

/**
 * Find low rent at 15% gross monthly income
 */
public function rent($income)
{
  return round(($income*0.15) / 12);
}

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

public function calculateLowRent($monthlyIncome): int
{
  return $this->calculateMonthlyRent($monthlyIncome, 0.15);
}

public function calculateMonthlyRent($monthlyIncome, $percentage)
{
  return round(($monthlyIncome*$percentage)/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 pushed in the code the risk that you, and the other developers, will pay less attention to their presence increases exponentially also propagating in the documentation 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 improving maintainability of your code base.

---

I'm creator of Inspector a Real-Time monitoring tool for Web Agencies and Freelancers.

If you have a PHP application that power your business, Inspector identify issues before your users are aware of them, keeping your business safe.

Try Inspector, it's free: https://www.inspector.dev

Comments

[Valerio]

I'm curious about your thought :)