DEV Community

Cover image for To Comment or Not To Comment
Robin
Robin

Posted on

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 {
   ...
}
Enter fullscreen mode Exit fullscreen mode

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);
Enter fullscreen mode Exit fullscreen mode

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);
  ...
}
Enter fullscreen mode Exit fullscreen mode

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;
  }

  ...
}
Enter fullscreen mode Exit fullscreen mode

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

Discussion (2)

Collapse
jhelberg profile image
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...

Collapse
chuniversiteit profile image
Chun Fei Lung

There are some pretty good arguments in here!

I’ve been spending a lot of time reading about all the various perspectives on comments recently and am currently gathering opinions via a survey on comments. You’re all kindly invited to participate! 😄