In this lesson, you'll be introduced to a standard for writing comments in JavaScript.
As your projects get larger, you'll want to start getting into the good habit of documenting things as you go along. This can have many benefits, one of the best being that editors can often read JSDoc and will use them to provide you with helpful hints as you write code (Intellisense).
This short lesson will just show you what it looks like. If you want to know more about the syntax, check out JSDoc.
## Where to Add Comments
A good place for documentation is functions:
/** Checks a position for four items in a row */
function checkConnectFour(row, col) {
// ...
}
How to Add Your Comments
The standard followed by most JS developers is called JSDoc. It starts with the /** marker and ends with */. It can span multiple lines too, and use a special JSDoc syntax:
/**
* Checks a position for four items in a row
*
* Relies on global variables `board` `lines`
*
* @param {number} row - the index of the row of the position to check
* @param {number} col - the index of the column of the position to check
*/
function checkConnectFour(row, col) {
// ...
}
You don't need to use all of the special syntax, just be aware that it exists.
You can always ask ChatGPT to help you write your comments too, just ask it to "write a JSDoc comment for this function" and it will do its best to help you out. Be sure to check the result though, as it's not always perfect and is often far too verbose.
Learn by Doing
Add some JSDoc to your functions in your module project. You don't need to use any special syntax if you don't want to, but a high-level description of each function and any important details like reliance on global variables should be added.
Please be sure to push your code to Github when you're done.
Summary: JSDoc for JavaScript Comments
You've
- Appreciated the usefulness of comments in maintaining and understanding your code, especially as your projects grow in complexity.
- Been introduced to JSDoc, a convention for commenting in JavaScript, which can enhance the functionality of code editors through features like Intellisense.
- Learned that comments should at least be placed above function declarations to describe what the function does.
- Understood how to structure a JSDoc comment using
/**to start and*/to end. - Discovered the special syntax within JSDoc, such as
@param, to give detailed information about function parameters.