John de Michele wrote:Frankey,
I would argue that in your second example, the method should have been named reverse() or reverseString(). Then you wouldn't need a separate comment on what the code is doing. That's what is called self-documenting code.
As for my documentation, my work doesn't have rules requiring me to document my code. However, since I actually want other people to be able to use it, I always use a combination of javadocs and self-documenting code. I very rarely use internal comments, because I try to make my code as clear as possible so that someone who is familiar with the language I'm coding in, or even a reasonably experienced programmer who doesn't know the language, would know what was going on.