When you write code, comments allow you to leave notes for people to read. They explain to you and others what your code does. The computer will ignore them when it processes your code.^[1]

You never know when you'll revisit your code. Maybe you'll come back to it in a year and try to remember what you were doing. You also never know when someone else will visit your code. Maybe they'll want to improve it or learn from it. Good comments make this easier.

Comments in different languages

In HTML, a comment starts with <!-- and ends with -->. It can be on one line or it can be a block that takes up multiple lines. Here's an example:

<!-- This is a comment. -->

In CSS, a comment starts with /* and ends with */.

/* This is a comment */

In JavaScript, comments can look like CSS comments. For quick single-line comments or comments at the end of a line, they can also start with //.

/* This is a comment. */
// This is also a comment.
let x = 0; // Another comment

Things you can use comments for

You can use comments to:^[1][3]

• Organize your code and say what each code block is for (Example: "Column 1")
• Explain a debugging choice so no one undoes your fix later
• Mention issues that need fixing later (many devs start these comments with TODO:)
• "Comment out" blocks of code that you don't want to use right now (e.g. not working, obsolete) but might play with in the future
• Debug by temporarily disabling parts of code so they get skipped
• Give credit to where you found a code snippet

Comments are especially important if other people will be editing your code. Comments reduce confusion and help your coworkers get up to speed faster.

Best practices

Sometimes, you might do an odd-looking bug fix or coding choice. It might not make sense to a newcomer who looks at it, but it actually has an important function. This is a great place to put a comment explaining why we need that code.^[3] Then, people are less likely to delete it without realizing that's a bad idea. Here's an example you might see on wiki templates:

<!-- Line breaks are commented out so they don't appear in unexpected places when the template is used -->

Many people copy code snippets from the internet. (That's the point of Stack Exchange.) It's good to credit your source with a link. Then, you and others can always (re)visit the source for debugging or learning help.^[3] Example:

/* Link trick thanks to https://stackoverflow.com/questions/5379752/css-style-external-links */

Avoiding common mistakes

Don't use comments to over-explain obvious things.^[3] For example, here is an unnecessary comment:

let x = 0; // x is 0

It's easy to see that x is 0, so you don't need a comment for that.

Also avoid comments that are:^[3]

• Trying to compensate for awful code (you should write good code too^[4])
• Vague/confusing (The purpose of a comment is to make code less confusing)
• Warning users away from your code because it's too complicated (Maybe you should try simplifying your code so it isn't a mess)

See also

• Accessibility
• Debugging
• Templates

References