Some people would argue that code should be self-documenting, with no need to add comments to the code at all, providing it is written well.

Personally, I believe the more documentation, particularly around complex areas, the better. This short article explores some reasons why.

Comments should focus on ‘why’

It is important, however, for comments to focus on ‘why‘ the code is doing what it’s doing, rather than ‘what‘ it is doing.

For example, the following is a pointless comment since a developer proficient in the language should be able to read and understand it:

 * Add the two values and return the total
$one = 1;
$two = 3;
return $one + $two;

The part that is not clear is why $two has been assigned the value 3, since that would cause head-scratching by anybody reading the code. This is of course just an illustrative example and it is bad practice to name a variable in such a way, but let’s assume there’s a good reason.

A better comment would be:

 * The variable $two is given the value 3.
 * This is due to the {specific reason} and
 * it should not be renamed to $three for
 * {specific reasons why not}.
 * Do not change it because this has previously
 * caused issues with {details of previous issues}.
$one = 1;
$two = 3;
return $one + $two;

Comments should detail your investigation

Sometimes a huge amount of work can go in to debugging a particular issue, and the outcome might be a single line of code.

Another developer, or indeed your future self, might look at this code and think it doesn’t make sense and believe there’s surely a better way.

You must therefore remind your future self that there is logic behind your decision.

 * Added:
 * $value = $this->getSomething();
 * Do not remove `$value =` because it is important,
 * removing it causes {specific issue details here}.
 * This may appear to be redundant code since $value
 * is immediately overridden, however the initial 
 * assignment is important due to an issue in the 
 * core code which we are unable to access to change.
 * This was discovered during a Production issue where
 * visitors were reporting {details of specific issue}
 * which was captured in {ticket reference} and has now
 * been resolved by this addition.
 * @see \Some\Core\Core\Class::getSomethingRelatedThing()
 * @see \Another\Core\Class::someStrangeMethod()
$value = $this->getSomething();
$value = $this->getSomethingElse();

This is again an illustrative example, since the initial declaration of $value is indeed redundant, however we can safely assume from the comment that the assignment is intentional and not a mistake, and should not be changed.

This is a helpful warning to other developers, and your future self, that the author was not being complacent.

Show that you looked at other approaches

Another use of comments is to highlight that the approach taken is the correct one, since other approaches might seem more appropriate at a glance and it would be tempting to refactor something to use the obvious choice.

If you have already assessed other options and they were not appropriate, a well written comment will save a colleague or your future self some time exploring the same routes.

 * Note: The $cart class includes a
 * method `getTotalIncludingTax()` however
 * this is not fit for purpose because
 * {specific reason it is not valid}.
 * The other implementation using
 * $taxCalculator->calculateTotal($cart)
 * is also not value for us because
 * {reason this is also not valid}.
 * Therefore in this approach we take
 * the subtotal and simply add the tax
 * value. More details in {ticket ref}.
 * @see \Some\Class::getTotalIncludingTax
 * @see \Another\Class::calculateTotal
$subtotal = $cart->getSubtotal();
$tax = $taxCalculator->getTax($subtotal);
$total = $subtotal + $tax;


Of course there is no substitute for well-written, self-documenting code.

However when something caused you to scratch your head or is not immediately obvious ‘why‘ something is written the way it is, a well written comment will cause zero performance impact whilst benefiting your team immensely.

Photo by Martin Wilner on Unsplash.

Published by Joseph McDermott

A certified Magento solution specialist with twelve years experience leading ecommerce development projects, converting complex problems into elegant technical solutions.

Leave a comment

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.