Is it bad to comment your code? People have strong opinions either way and it can get...intense. It's not exactly tabs-vs-spaces but it's close. Some engineers think that "truly" self documenting code doesn't ever need them. While I do love readable code, I think comments can be invaluable if used properly. So let's jump into the flame war and talk about what makes a good comment.
What vs. why
A common critique of comments is that they're redundant:
Once you get better at reading code, these kinds of comments become useless. I think bad comments point out the what, while good comments explain the why. Here's the rule of thumb I like:
A comment should be added to answer a question that the code can't.
If you aren't confused by what a piece of code is doing, but rather why it's doing it at that moment, then a comment could help.
A frustratingly real world example
Take a hypothetical situation where we're debugging user migration code:
Why are we deleting default_name? Our first instinct is to search the repo for other instances of default_name, but we just find a typing that says it's a string. We ask our team, but no one knows, and the guy who wrote it quit. Is it just because we're using the newer username field now? We're forced go to Slack and ask if anyone uses it. Turns out, the subscriptions team has a legacy system that uses default_name's existence to determine if a user is from v1 or v2. Since we're migrating to v2, we delete the field.
Adding an explanation
Now that we know why we're doing it, we could put it into a function with a descriptive name like makeSureUserAppearsNewToSubscriptionAPI. Some people would do this, but it doesn't always make sense to add an entire function. Instead, a comment could solve the problem.
It instantly explains the situation without anyone else's help. And if a future dev has questions, they'll know what team to talk to. And if it changes, we don't need to edit any other functions, just this one comment.
“That's bad code”
I can already feel the skeptics saying that the comment wouldn't be needed if the system was designed better, if there was better knowledge sharing, or if there were real docs. And you know what? They are absolutely right.
...if we lived in a coding textbook. In real life, code gets pushed out quickly, legacy software does weird stuff, tickets are too vague, and internal docs are always a low priority. To me, comments are a clunky solution, but a clunky solution is better than no solution. However, that doesn't mean we should overdo comments.
Less is more
Just because I like comments doesn't mean I like a lot of them. If you find yourself writing things that sound more like helpful tips that succinct explanations, you should move them into your team's docs, or at the very least to your personal notes.
Keep them short
Comments will always be controversial, so the shorter the better:
Longer comments should be formatted
If you need more than one line, try breaking out the confusing piece of code into a function, and then add a jsDoc style comment. This is super handy because it lets you add code information that appears when you hover over the function. These comments take more time, but they're much less controversial due to their utility. Some of the most ardent fans even advocate for jsDoc over TypeScript. I don't know if I'd go that far, but the hover effect is super handy, and I love when codebases use them.
To don'ts
Another common type of comment is TODO: and then some task. This is possibly the most controversial comment of all. Personally, I think they're great before you complete your PR. I always scan my PRs to make sure I got to everything I wanted to.
However, if you find something too big to be done in the scope of your current work, I wouldn't recommend these comments. Instead, you should make tickets, which will ensure that it will get on the team's (and product manager's) radar. If it's a personal project it's not a big deal (most people don't use Jira for fun), but it's not a good sign when a codebase is littered with TODO comments. It usually means theres a breakdown in process somewhere.
Go out and comment responsibly
Helping other people understand your code is a key part of being a great developer. Comments should be another tool in your belt, if used with discretion. I hope this helps, and if you have any comment conventions you like to use, join the conversation on Reddit to leave a comment!
Happy coding everyone,
Mike