re: What are the least intuitive fundamentals and best practices in software development? VIEW POST

TOP OF THREAD FULL DISCUSSION
re: Non-intuitive: There's generally no correlation between amount of code and usefulness to a user. There is however a definite correlation between am...
 

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.

code of conduct - report abuse