Nothing is better than a well-documented libary. Code which is heavily commented is a blessing of its own, albeit though rare. So why is it that people prefer to omit comments or just not bother to write any at all? I mean, it's not like it's not creating any harm, right?
I want to talk about writing code and my experiences. I think code should be written in a away which is understandable to the programmer. Correct indentation, occasional spacing between instructions and clear instructions all go a long way to make the code legible and easy to read. Remember - it's not the computer who necessarily suffers, but rather the author.
With that being said, how can comments help us understand the code? Well, most of the time, comments are unnecessary. In higher-level languages, your function names, your variable names, control-flow statements and everything else with names ARE your comments. Take a look at this, for example:
Player player = Bukkit.getPlayer("Slinthn");
Is there really a need for a comment? I'd argue no - even though I took this line from a Minecraft plugin and you may never have seen something like this before, I think it's very clear what's going on: A variable of type Player is being assigned to the value of a currently connected player to the server. It should also be fair to assume that this Player class is used to manage the player's stats, like health and xp. Putting a comment here would overdo it; what would you even write? "Get player object from Bukkit?" Is it not already obvious enough?
I do find posts like this funny, for example, this and that. But seeing posts like these raises the bigger question - why? Are we, the programmers, not writing maintainable, readable code? Is the code just too complex to be automatically documented via variable names but we aren't writing comments just because we're lazy? I find when writing in lower-level languages, like assembly languages, it is absolutely crutial to write a comment on almost every single line. I first realised this when I came back to a file which i hadn't edited in about 2 weeks and I was trying to understand the code. It's not that I couldn't understand what was going on, it's that it took time. Time I could have used to be writing code. It was from here on out that I decided to take the time to comment my code. Not only do I feel so much more comfortable, but if I come back to the code in the future, I will have no trouble understanding what's going on.
I think the biggest issue comes from the thought that you'll be able to understand your code after 5 minutes, or a day, or a week. Although this may be true, another truth is that you can never write enough comments. Comments should aid your understanding of what's happening. It can be as simple as an overview, for example what this next section of code will do, or it can be as elaborate and intricate as to describe what each and every line is doing. Whichever style you choose will depend on you.
Another issue comes from the idea that it takes time to write comments, which is absolutely true, however, I recon I've spent more time trying to understand the code I've written in the past than actually writing comments. Take the time to understand your code and to document it. If anything, from writing comments, I've managed to fix some issues, because I'm stepping through the code line by line and really understanding the instructions.
In conclusion, comments are a brilliant way to remove frustration. It's a habit we all need to get into, as well as extra time we need to give up, though at the end of the day, everyone benefits if we were to write just even one more comment.