A bit of a controversial topic, code comments.
From what I read there are at least 2 major thoughts on the internet, and in practice, there might be at least a third. So let's see what I mean with this.
No comments, period.
There is a group of people that say that there should be no need to add comments to code. Functions (or methods in case of classes) should be self explanatory.
Code should be so expressive, that it's clear what is happening in the code in an instant, and no it will leave no room for interpretation.
Comment everything
The other thought, is to document everything, parameters that go into the function, the behaviour of the function, the result, any exceptions etc.
With obviously the biggest risk, that code gets refactored, but the comments don't.
So how to deal with this?
I think that code should have comments, but those comments should follow some guidelines*.
- Comments should add something. With this, I mean that comments should explain what is happening as soon as there is a reason to think that there is some unclarity.
- Comments can help to explain what the code is supposed to do. Lets be honest, we all make mistakes, so at least others (or in the future the author of the code) can look back and see what the intent was.
- It is also important that comments don't rely on things like arguments being used and such. Because that is the fastest way to ensure that comments get out of date.
Just adding functionality to a function, or having to add a argument in the future to make the algorithm work (as the comment says it should) might make it outdated. - Arguments should be commented for their intent. This might seem counter intuitive with the statement above, but it is different. The intent of a argument should not change. If an argument is used to indicated a maximum number of iterations than that intent won't change. Independent on how the algorithm works.
In conclusion
So I think that comments should be added. They can, and should be used to clarify intent of the functions. And thus the idea behind the code.
I don't believe that in practice it is possible to write code that is so easy to read an understand that nobody needs comments. I can think of a way that this might be accomplished by having really simple functions, but that will result in a big calling tree (at least in memory of the developer). And getting a feeling for the way the calling tree is build, means that it still needs a lot of mental capacity to understand what is happening. While just adding a few lines to explain what the intent is, makes things so much simpler to understand.
guidelines*:
When a tool like javadoc, doxygen and the likes are used, then more 'comments' will need to be written. But in those cases, I think that comment should be read as (api) documentation, disguised as comments and are a completely separate topic.