Stop Commenting Your Code(antonpug.com) |
Stop Commenting Your Code(antonpug.com) |
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.
Reading english (or whatever your native language is) is much much faster than parsing 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!
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.
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)