Comments

Apr 29, 2016•
3 min read

programmingprinciples

When programming we are using some programming language to describe a solution for a problem, to define behaviour or the flow of a computation. And we do it using a language that is not human, and it’s not our mother language, therefore we inevitably feel the need to leave comments and make it as readable as possible. By other words, most of the times we comment to balance the unreadability of our code.

So the challenge is to comment only if really necessary and inevitable and not as the solution. Only comment when it really needs to be, when you need to explain why a certain unexpected expression or value is there and you can not let it express with clear code.

The software we develop should read as much as possible as a narrative. The ultimate source of truth is the code itself while the comments easily become obsolent or even a lie upon the code.

Comments are a discret way of making us worse developers and a great convinence to our lazyness.

Also, to comment usually comes together with breaking the Tell, Don't Ask principle.

Let’s jump to an example:

intnumberOfItemsEligibleForDiscount(Salesale){inteligibleItems=0;for(Itemitem:sale.items()){// if this item cost more than 50 euros and it's from the music category...if(item.cost()>50.0&&i.category().equals("music"))eligibleItems++;//then we increment the eligibleItems}returneligibleItems;}

Alright. What does exactly mean to an item to cost more than 50 euros and being from the music category?
It means it’s eligible for discount!
So why having this knowledhe within a function whose porpuse it to tells us how many items from a sale are eligile to have discount?
Next to this, how can we reduce the ammount of code written here?

“Oh cool, we can use java 8 streams!”
So we go and we refactor this code. We reduce it by 5 lines and we make it somewhat more declarative.
Still confusing. And, more than that, we keep having, within this function, business logic knowledge that should have a meaning and existence on its own, by itself.