Why you should be commenting your code, even if you’re the only contributor

Comments in code can be a lifesaver. They can explain what the code is doing in plain English (or whatever language you’re using) and can help show where something might be. But if you’re working on a solo project, you might feel the pull to not add any comments to your code. Besides, you know what you’re doing, and you’re going to be only one looking at the code, right? Wrong. Even if you’re working on a solo project, you still should be commenting you code. Here’s why.

Helps keep you organized

Code can get very messy very quickly. There are thousands upon thousands of lines of code that come with WordPress and other great applications on the web. So how do contributors keep track of what’s going on in all of that code? Comments. That’s how. Now, your app or theme or plugin or other web-related code probably won’t be thousands of lines of code long, but you can still get lost in all of the code. That’s where comments come into play. I’ve made it a habit of creating a table of contents at the top of every functions.php file so that I have a general idea of where a function I’m looking for might be. And then I have comments before each function definition — known as DocBlocks — so I know exactly what each function does and if it’s the one I’m looking for. Commenting your code is going to save you time and frustration.

Great way to figure out how to solve a problem

One of the few things that I learned early on that immediately changed my thinking was pseudo code. If you don’t know, pseudo code is more of a process than a real thing. It’s thinking through the solution to the problem and writing the solution out in English rather than code. It makes you think through the issue rather than running right in and having no idea what you’re doing. So how do comments come into all of this? Well, the comments can be your pseudo code. Before you do anything with your file or function, you can write comments in it about where things will be done and how you’ll solve the problem. So when you finally start writing the code, you’ll know exactly what you’re doing. And again, commenting your code is going to save you time and frustration.

It’s good practice for when you’re in a group

But most importantly, it’s good practice for when you’re working in a group later down the road. Sure, this project might be a solo gig, but eventually you’re going to be working with others on a project. And they’re going to have to parse your code. You might know the code like the back of your hand and be able to find everything quickly, but your partners won’t. They’re going to come in without the knowledge of the code and will likely be very confused. And that’s going to slow down the team’s process. And nobody wants that. Plus, if you’re working on a theme or plugin for others to use, your comments are going to make your users extremely happy. That documentation is going to make life so much easier for them if they need to fix an issue or add a customization. So make sure your commenting your code on every project, even if you’re the only contributing.