Why it’s important to comment your code

I’ve recently heard a few people saying that it’s bad form to comment your code — that it makes your code dirty and cluttered, and that it encourages poor coding syntax.

Everyone has their own coding preferences (tabs! Camel case!), so in light of people speaking up about commented code, I felt this would be a good time to talk about one of mine. Here’s why I always comment my code:

1. Nobody can read your mind. When you’re working in a team, whether it’s with one other person or 30 devs and engineers, people need to understand not just what you did (which your clean code should make clear), but why you did it. It’s pretty easy for me to see that you’ve written a bunch of functions; it’s more difficult for me to understand why you wrote them the way that you did and what it is they’re all doing.
2. Sharing is caring. In a perfect world, you’d have a handoff discussion with everyone who will have their hands in your code. In reality, you’re working on projects with other developers simultaneously, many of whom might not even be in the same country as you. Keeping your reasoning to yourself is just rude.
3. Memories are not forever. I guarantee that you’re not going to remember every line of code you’ll write. As much as you might think that you’re doing something so incredibly significant that it will be etched into your brain until the end of time, well, I’m sorry to break it to you, but you’ll probably need to reacquaint yourself with your gorgeous keystrokes after a coffee break. Leaving a little breadcrumb so that you don’t get lost in your own masterpiece is something your future self will thank you for.
4. This community is open source. One of the things that really helped me to understand coding — syntax, structure, and pattern — was to read through other people’s code. I spent many evenings digging through Github, trying to determine which function was responsible for which type of webpage sorcery. If you’re truly interested in growing the dev community and in helping others learn, you’ll allow them a glimpse into your process by leaving useful comments in your code. Good comments can help new (and experienced) devs understand the value of approaching challenges with a new perspective.

If you’re obsessed with clean code, the goal isn’t necessarily to have the fewest lines in your file — it’s to make sure that all the lines that you do have are really easily understood.