One of many things nerds like to spend far too much time debating is whether or not to comment their code. On one hand, comments make code a lot easier to understand, but on the other, many people claim that good code is self-documenting.
If you haven’t been writing code professionally for long, it probably seems totally obvious that comments help you understand code you’re new to or haven’t looked at in a while. For the most part, they do help. The problems are that bad comments really don’t help and that comments only help if they’re correct.
What makes a comment a bad comment? If you’re going to add comments, they should explain why the code does what it does, not what it’s doing. Take the examples in this reply to a reddit thread – it’s totally unhelpful to add comments like “//Reduce’s player counter by 1” to a line of code like “mageCounter–;” That comment doesn’t add any information that isn’t in the code. Of course the counter is being reduced by 1, that’s obvious. What’s useful is knowing why the counter is being reduced.
Not only is that comment not helpful, it wastes space. The more comments like that you have, the less code you can see on the screen at once. Yes, that sounds really trivial, but seriously, it’s incredibly annoying to have to scroll up and down to see the whole method.
How can a comment be incorrect? If the code changed and the dev who changed it forgot to update the comment. Out of date comments can waste huge amounts of your time when you need to change a piece of code because everyone naturally assumes the comment is correct. If it wasn’t, why would it be there? Sadly, developers are only human and sometimes we get so excited about the code finally working that we forget to update the comment.
That’s part of why some people say that you should not have comments, that they’re a sign you didn’t name your variables and methods and classes well enough. It is true that if the names in your code are their own comments, then they won’t fall out of date the way actual comments can. On the other hand, there are limits to what variable names can tell you. I think the most important comments are the ones that explain weird code that works around a bug in an API or something strange you did for performance or just a workaround for a design choice that didn’t pan out long-term.
Those are the kind of things that self-documenting code just can’t document. There’s no method name that can explain why some of your tests use one dummy mailserver and other tests use a different one because there’s no single dummy mailserver that handles all of the test cases you need. At least, not without that method name being terrible code on its own and at that point, you might as well use a comment no matter how much you normally oppose them.
My view of comments is somewhere in the middle – I think they’re a great tool for keeping track of what you’re doing while you code, but once you’ve written the code you should only leave in the comments that are important to help understand it. As much as possible, you really should rely on good naming, if only because good names are always a good idea :)
And in general, I think absolutism is a waste of time. Even otherwise excessive “here’s what the code is doing” style comments could be really helpful if you’re working in a low level language or doing something clever with pointers where it’s just not immediately clear what the code is doing, let alone why. It’s more about context than it is about hard and fast rules. Surely you didn’t go into programming because you ever wanted to be certain about anything ;)