Discussion on: JavaScript Best Practices for Beginners

View post

It might seem unnecessary at first, but trust me, you WANT to comment your code as best as possible. What happens when you return to the project months later, only to find that you can't easily remember what your line of thinking was. Or, what if one of your colleagues needs to revise your code? Always, always comment on important sections of your code.

I understand your point, but I tend to not agree with this because code should explain itself, otherwise, we would use Machine code directly, for me, Programming languages (at least high-level ones) tend to be quite readable already if you code in such a way that is understandable. If not, you might want to look into clean code examples and principles, they can make a huge difference.

"Good code should explain itself with the need for few comments"

Another bad thing about comments IMHO is that you're creating a new "dependency" that you need to update whenever you edit that code, if you forget to update the comment after updating the code it will result in conflicting explanations, on one side the comment says the code does one thing but the code tells you it does another thing.

As you pointed out, I prefer using comments to explaining the line of thought of complex functionality, were just the code must not explain it correctly, or it uses an abstraction of some kind, which cannot be interpreted just by looking at the code.

I think comments can be useful, but it is not a sign of good code IMO.

Mike Talbot ⭐ • Jun 3 '20

Totally agree:

     function process(b) {
       //Get the angle
       let a = b.rotation
       //Rotate
       a += Math.PI
       //Return the rotated angle
       return a
   }

     function getReverseAngle(gameObject) {
          return Math.PI + gameObject.rotation;
     }