I recognize three kinds of comments that have different purposes.
The first kind are doc block comments. These are the ones that appear above functions, classes, class properties, methods. They usually have a distinct syntax with tags, like:
/*
* A one-line description of this function's job.
*
* Extra details that get more specific about how to use this function correctly, if needed.
*
* @param {Type} param1
* @param {Type} param2
* returns {Type}
*/functionaFunctionThatDoesAThing(param1, param2) {
// ...
}
The primary thing this is used for is automatic documentation generators. You run a program that scans your codebase, looks for these special comments, and automatically builds a set of documentation that you could, say, publish directly to a website. IDEs can also use them for tooltip popups. Generally, you want to write these like the reader won’t have the actual code to read. Because they might not!
The second kind is standalone comments. They take up one or more lines all to themselves. I look at these like warning signs. When there’s something about the upcoming chunk of code that doesn’t tell the whole story obviously by itself. Perhaps something like:
/* The following code is written in a weird way on purpose.
I tried doing <obvious way>, but it causes a weird bug.
Please do not refactor it, it will break. */
Sometimes it’s tempting to use a standalone comment to explain what dense, hard-to-read code is doing. But ideally, you’d want to shunt it off to a function named what it does instead, with a descriptive doc comment if you can’t cram it all into a short name. Alternatively, rewrite the code to be less confusing. If you literally need the chunk of code to be in its confusing form, because a less confusing way doesn’t exist or doesn’t work, then this kind of comment explaining why is warranted.
The last kind are inline comments. More or less the same use case as above, the only difference being they appear on the same line as code, usually at the very end of the line:
dozen = 12 + 1; // one extra for the baker!
In my opinion, these comments have the least reason to exist. Needing one tends to be a signal of a code smell, where the real answer is just rewriting the code to be clearer. They’re also a bit harder to spot, being shoved at the ends of lines. Especially true if you don’t enforce maximum line length rules in your codebase. But that’s mostly personal preference.
There’s technically a fourth kind of comment: commented-out code. Where you select a chunk of code and convert it to a comment to “soft-delete” it, just in case you may want it later. I highly recommend against this. This is what version control software like Git is for. If you need it again, just roll back to it. Don’t leave it to rot in your codebase taking up space in your editor and being an eyesore.
I recognize three kinds of comments that have different purposes.
The first kind are doc block comments. These are the ones that appear above functions, classes, class properties, methods. They usually have a distinct syntax with tags, like:
/* * A one-line description of this function's job. * * Extra details that get more specific about how to use this function correctly, if needed. * * @param {Type} param1 * @param {Type} param2 * returns {Type} */ function aFunctionThatDoesAThing(param1, param2) { // ... }The primary thing this is used for is automatic documentation generators. You run a program that scans your codebase, looks for these special comments, and automatically builds a set of documentation that you could, say, publish directly to a website. IDEs can also use them for tooltip popups. Generally, you want to write these like the reader won’t have the actual code to read. Because they might not!
The second kind is standalone comments. They take up one or more lines all to themselves. I look at these like warning signs. When there’s something about the upcoming chunk of code that doesn’t tell the whole story obviously by itself. Perhaps something like:
/* The following code is written in a weird way on purpose. I tried doing <obvious way>, but it causes a weird bug. Please do not refactor it, it will break. */Sometimes it’s tempting to use a standalone comment to explain what dense, hard-to-read code is doing. But ideally, you’d want to shunt it off to a function named what it does instead, with a descriptive doc comment if you can’t cram it all into a short name. Alternatively, rewrite the code to be less confusing. If you literally need the chunk of code to be in its confusing form, because a less confusing way doesn’t exist or doesn’t work, then this kind of comment explaining why is warranted.
The last kind are inline comments. More or less the same use case as above, the only difference being they appear on the same line as code, usually at the very end of the line:
dozen = 12 + 1; // one extra for the baker!In my opinion, these comments have the least reason to exist. Needing one tends to be a signal of a code smell, where the real answer is just rewriting the code to be clearer. They’re also a bit harder to spot, being shoved at the ends of lines. Especially true if you don’t enforce maximum line length rules in your codebase. But that’s mostly personal preference.
There’s technically a fourth kind of comment: commented-out code. Where you select a chunk of code and convert it to a comment to “soft-delete” it, just in case you may want it later. I highly recommend against this. This is what version control software like Git is for. If you need it again, just roll back to it. Don’t leave it to rot in your codebase taking up space in your editor and being an eyesore.