DEV Community

Discussion on: What are the least intuitive fundamentals and best practices in software development?

Collapse
 
cjbrooks12 profile image
Casey Brooks

Comments should never be used to describe what code is doing. It should describe why it's being done the way it is. You've got the code right in front of you, but if it isn't immediately obvious what it's doing, a comment explaining the why is quite nice. Note that these comments rarely go at the declaration site of a method, they're more effective when they're written inline, as close to its relevant code as possible.

And on the other extreme, don't go so deep into the why comments that the code becomes difficult to read. The code is still the shining star, make sure it is still easy to find the code amongst your comments. Anything longer should go in the official documentation.