To Comment or Not To Comment

Sometimes I feel like writing comment is a controversial topic in programming. Some will take the stance of:

Code is like humor. When you have to explain it, it’s bad.

Of which, I don't 100% agree with.

---

Mis-interpretation

Let's take a bit of a bad example:

function applyDiscount(to: number, rate: number): number {
   ...
}

At a glance, the code is quite obvious: Apply discount to a number, pass on the rate and the function will return the final result.

Two months goes by and somebody else wanted to use this function and at a glance they use:

const finalPrice = applyDiscount(100, 10);

expecting the finalPrice = 90 but instead got finalPrice = -900

In this case, there's an illusion where the code is already self-documenting and self explanatory, but interpretation of a word between each developer might be different! What rate means for the original coder is the rate of discount after it is divided by 100. But the next coder who tried to use it interpreted it as a percentage number.

Naming things is always regarded as one of the hardest thing in programming. Mis-interpretation will always happen when glossary of words between developers are different.

---

Too Much Focus on What but not Why

Consider this bad and exaggerated example:

function applyDiscount(to: number, percentage: number): number;

...

function submitOrder(order: Oder) {
  order.setFinalPrice(applyDiscount(order.subTotal, 10);
  ...
}

Sure now the code is obvious, every order will be given 10% discount. But it's now missing an important context on:

Why should every order be applied 10% discount?

Most of the time we can easily understand the code on what it does by tracing it line by line. But when things gets complicated, only focusing on what the code does loses the context where we need to know

Why the code is written as it is?
Or, why there's a branching condition?

---

Comment your intent

Most of the times, comment should never explain what the code does. But rather what the intention is.

Let's again take a look of this simple example:

function doPayment(cardNumber: string) {
  if (isVisa(cardNumber)) {
    processPaymentOnlyForVisa(cardNumber);
    return;
  }

  ...
}

Sure we know how to read that there's a special treatment for payment using Visa. But after maybe 1-2 months or when the original coder leave, the context of why Visa payment should be different is lost.

It might be business decision, it might be caused by some technical hurdles.
But as long as the intention was not documented, the cause is lost for the next person who touched the code.

---

Cover image credits to: Artur Shamsutdinov

Comments

[Joost Helberg]

Nice one and ery important. Good example. Business-case driven decisions (all of them) should also be documented, consider literate programming. First write documentation, then code. And all in one file...