If you think you need to comment your code, think again.
There is a difference between documentation and commenting.
A documentation states what a method does, and it resides outside code blocks.
Often, comments are used to explain how a piece of code works. If a method is written
well, then do you need the comments?
If I show a piece of code that is confusing, you can (a) write a comment to describe
how, or (b) refactor the code so it is obvious what it does.
Option (a) may result in further confusion. Also, when writing comments, I have seen
developers pour their emotions and opinions, which serves as distraction and takes
us further
away from understanding the code.
Option (b) can help not only make the code easier to understand, it can help us make
it simpler.
There is beauty in simplicity.
In the wise words of C.A.R. Hoare, "There are two ways of constructing a software
design.
One way is to make it so simple that there are obviously no deficiencies. And the
other way is to
make it so complicated that there are no obvious deficiencies."
Back to writing comments.
Writing comments is like explaining a joke. Good code, like good
jokes, have to
be left for the reader to absorb (and enjoy).
