undefined | Better HN

0 pointssaas_co_de8y ago0 comments

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.

0 comments

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

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)"

antonpug8y ago

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.

antonpug8y ago

There must be an insane amount of cognitive overload when having to parse through 2x the number of lines because every line of code is accompanied by a line of comment.

Beached8y ago

Still requires more brain processing then plain English, and if your spending hours parsing code it is taxing and reduces your overall productivity.

j / k navigate · click thread line to collapse

0 comments

antonpug8y ago

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

saas_co_deOP8y ago

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.

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)"

antonpug8y ago

There must be an insane amount of cognitive overload when having to parse through 2x the number of lines because every line of code is accompanied by a line of comment.

Beached8y ago

Still requires more brain processing then plain English, and if your spending hours parsing code it is taxing and reduces your overall productivity.

j / k navigate · click thread line to collapse