Please please please, do not always write comments. Try to write code that does not need comments whenever possible. Proper variable, class and method names go a long way. If you think a block of code needs a comment, turn it into a method and give it a proper name instead.

Comments should be a last resort for cases where making the code self explanatory is not possible, and those should be rare.

About optimization:

Optimal code is code that fulfills it's purpose without observable issues.

If you try to make something faster without any prior complaints or measurements indicating that it being slow is an actual issue, you are not optimizing, you are just engaging in mental masturbation.

[–] JDubbleu@lemmy.world 19 points 1 year ago (1 children)

For my current job we've all agreed to take the approach of not writing comments that say what the code does, but why you did something the way you did. Probably about 90% of our code is uncommented because it just doesn't need to be, but every once in a while you have to do something out of the ordinary to get the desired behavior, and explaining why you made the weird decision you did is infinitely more helpful.

[–] dukk@programming.dev 1 points 1 year ago

This exactly. I love this approach to commenting and use it all the time. I also like to write doc-comments wherever possible; it’s saves time and makes working on an unfamiliar part of the codebase much easier.

load more comments (13 replies)