I recommend adopting the practice of commenting your code as soon as possible. Getting into the habit early can save you a lot of headaches further down the line, especially once you start working on larger projects.

What are comments and how are they used?

You may be able to tell from the term itself—commenting code is the process of making comments on your code. Essentially, it’s when you go through and explain what you’ve written in plain English (or whichever language you prefer).

There are generally two ways to comment your code: block comments and inline comments. Comments are usually ignored by compilers, meaning you can put whatever text you wish in them without causing your code to malfunction.

Block comments are declared with ‘/*’ and finished with ‘*/’. Compilers will ignore anything in between, whether it’s all on one line or spread across multiple lines.

/* This is an example of a block comment */

/*
Here is a second example
of a block comment
*/

Inline comments are declared with ‘//’. Anything behind the two forward slashes will be ignored by the compiler, provided it’s on the same line.

// This is an example of an inline comment

Why bother commenting your code?

Commenting your code has numerous benefits. Comments exist to provide us with a way of making our code more understandable for humans. I know it’s easy to think that there’s no point in spending the time to comment what you write, especially when you’re working on projects that may never see the light of day, but comments aren’t there just to help others understand—they’re useful for you as well.

When you’re working on large projects, commenting your code is essential. It helps remind you of what certain parts of your code do and, more importantly, why you chose to do it that way.

Coming back to uncommented code after a while is not fun. You may have since improved your programming skills and you’ll find yourself looking at something and thinking why in the world did I do it that way? Without a comment explaining the logic behind it, you might just go ahead and change it—except then it breaks a different part of your code. This has happened to me more than once, and I’ve decided I prefer avoiding those situations.

If you’re ever following a tutorial and you find yourself copying the code line by line, but you don’t really understand what it does, comment it! Forcing yourself to explain code and the logic behind it in your own words is super helpful when you’re trying to learn.

Comments are also great for debugging. If you have an issue and you suspect a certain line (or segment) is causing it, don’t delete it! By commenting it out instead, the compiler will act as though it doesn’t exist. If it turns out that wasn’t the culprit, you don’t need to spam Ctrl + Z or rewrite it from memory.

How to comment your code

There’s various different styles when it comes to commenting your code. Personally, if I’m explaining an entire section instead of each line individually, I’ll stick an inline comment on its own line at the beginning of the section. If I feel the need to translate specific lines, I like putting the comment on the same line, behind the code.

As for block comments, I primarily use them when I’m debugging. Ultimately though, your choice of style isn’t a big deal. It’s more important to keep it consistent, at least within the same project. Feel free to change it up from project to project until you find what you prefer the most.

Finally, do your best to explain the logic behind the code rather than the line itself. If all you’re doing is setting a variable to false, don’t bother putting “// Set x to false” with it. I’m certainly guilty of doing this, and it really doesn’t help anyone. Instead, explain why you’re setting that variable to false. What effects does it have on other parts of your code?

If you’re looking for more specific info about comments, check out this Wikipedia article.