Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Stop Commenting Your Code

antonpug.com

Post reply on HN
Print view View original

11–18 of 18 posts

Re: Stop Commenting Your Code

#11

Post by Beached »

antonpug wrote: post #9
saas_co_de wrote: post #6

Earlier quoted context omitted.

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.

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

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

Re: Stop Commenting Your Code

#12

Post by antonpug »

antonpug wrote: post #9
saas_co_de wrote: post #6

Earlier quoted context omitted.

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.

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

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.

Re: Stop Commenting Your Code

#13

Post by saas_co_de »

antonpug wrote: post #9
saas_co_de wrote: post #6

Earlier quoted context omitted.

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.

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

Re: Stop Commenting Your Code

#15

Post by cgore »

cgore wrote: post #14
antonpug wrote: post #3

Earlier quoted context omitted.

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

I could ... but I'd rather not comment too much :D

More seriously: yes, you should name functions/variables/etc. reasonably. And often if you write a comment, you will find you are actually explaining away a wart. But often you need to document business logic, code that needs to be written in a less than clear way for performance reasons, explanations of why you chose approach A instead of what would seem like another perfectly reasonable approach B, URL links for standard doc PDFs, and a million other little things.

There are comments that aren't necessary if you write your code better, but there's others that are needed even if you write your code perfectly.

Re: Stop Commenting Your Code

#16

Post by antonpug »

cgore wrote: post #15
cgore wrote: post #14

Earlier quoted context omitted.

I could ... but I'd rather not comment too much :D

More seriously: yes, you should name functions/variables/etc. reasonably. And often if you write a comment, you will find you are actually explaining away a wart. But often you need to document business logic, code that needs to be written in a less than clear way for performance reasons, explanations of why you chose approach A instead of what would seem like another perfectly reasonable approach B, URL links for st…

Documenting business logic works much better via Spec files - if you have BDD test files Given/When/Then format, that'll go a long way in describing functionality, in my opinion.

Re: Stop Commenting Your Code

#17

Post by antonpug »

saas_co_de wrote: post #13
antonpug wrote: post #9

Earlier quoted context omitted.

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…

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.

Re: Stop Commenting Your Code

#18

Post by dvddgld »

antonpug wrote: post #10
dvddgld wrote: post #8

Earlier quoted context omitted.

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 opti…

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.

I agree that heavy commenting can be a code smell
Post reply on HN