
Stop Commenting Your Code - antonpug
http://antonpug.com/blog/2017/11/29/stop-commenting-your-code
======
saas_co_de
> Heavy code commenting is a symptom of bad code.

I used to believe that comments were unnecessary for good code but eventually
found this to be false.

Now I do code annotation where every single line of code is commented.

This allows the entire program to be read as plain english which is much
faster and less mentally taxing than trying to read code.

~~~
antonpug
Sarcasm? Or am I misunderstanding your comment? :) You annotate "every line"?

~~~
saas_co_de
In most cases yes. I make sure the comments provide a complete plain language
description of the program.

Reading english (or whatever your native language is) is much much faster than
parsing code.

~~~
antonpug
It's not hard to understand what this.completePurchaseProcess(paymentInfo)
does.

~~~
saas_co_de
Right, it is not about whether or not the code is complex and difficult to
understand.

That is the traditional (and bad) commenting advice: that you should add
comments to code that is difficult to understand.

The point of commenting everything is to allow the program to be understood
entirely from comments, so that when you are maintaining a code base you
rarely have to read code, and instead are working with native language.

I would comment your example like this:

    
    
      // complete purchase process
      this.completePurchaseProcess(paymentInfo)
    

When you have "complete purchase process" written out as english words you can
process that much more quickly than
"this.completePurchaseProcess(paymentInfo)"

~~~
antonpug
How often do you actually read through the code, trying to understand what's
happening and you _need_ english language? Once you read an english
description - do you still often have to look at the code to understand what
is _really_ happening? //complete purchase process - what does that mean? When
you look at the method, I see exactly what's being called and with what
parameters.

------
cgore
No.

~~~
antonpug
Could you be a little bit more constructive? It's okay if you disagree - but
I'd be curious to hear your side.

~~~
dvddgld
I like your article and the example you used, code clarity is vital. Poor code
is often accompanied by many poor comments which only helps in overwhelming
the next poor soul who has to read the code.

However, I think that the larger the project, the more sense it makes to
comment heavily. Again, code clarity needs to be a priority, but so does
comment clarity, so much time is spent reading code by humans who are
optimized to parse natural language. So we should cater to our users, not just
the users of our executable, but the users of our source too!

~~~
antonpug
Some commenting is okay and necessary. The point is that generally, if you are
adding heavy commenting, you can probably refactor the code in such a way that
commenting is not necessary. Even in a large codebase.

~~~
dvddgld
I agree that heavy commenting can be a code smell

