JavaScript Code Comments

Objectives and Overview

This lesson introduces code comments, a crucial programming concept. You’ll learn the syntax for adding comments to your JavaScript code and practice adding comments.

Lesson Objectives:

  • Understand the purpose of comments and how to add and remove comments from JavaScript code.
  • Demonstrate that you understand the JavaScript comment syntax by adding comments to a sketch.

JavaScript Code Comments

Adding comments to your code is a core aspect of programming. Comments are an effective way to document and explain your code. It’s helpful to anyone in the community reading your code, but it’s also useful to clarify your code to yourself. There are many times you might revisit a project at a later date and comments can provide helpful notes about your intentions. This is an especially solid practice when your project becomes increasingly complex.

Going through and adding comments to your code is a great way to solidify your understanding. Sometimes if you’re unable to explain what you’re doing in a comment or series of comments it sheds light on a piece of your code that needs clarification.

Adding Comments to Your Code

There are two ways to add comments to your JavaScript code: single-line and multi-line. Single line comments are created by adding two forward slashes to your code: //. Let’s take a quick look at an example of a single-line comment:

// this is a single-line comment in JavaScriptconst welcomeMessage = 'hello, welcome to the comment example';

Comments can also be written in multiple line blocks with the /* and */ characters. Any lines inside these characters are comments. Let’s look at an example:

/* this is a multi line comment this could be formatted better... check out the 'Best Practices' section next to see how! */ const nextMessage = 'hello, this is the second comment example!';
Code language: JavaScript (javascript)

That covers the syntax for creating JavaScript comments. Now let’s dive into some best practices and suggestions around the syntax.

Best Practices for JavaScript Commenting

Airbnb’s Engineering Team is one of the most respected teams in the JavaScript community, and they’ve created a JavaScript Style Guide that many rely on for JavaScript best practices. Many of the recommendations for best practices in this course are pulled from their recommendations. While you can effectively use comments without paying attention to community best practices, it’s good to be in the habit of paying attention to these things. As you begin sharing your code with others and especially if you contribute to the open source community, you’ll want to be mindful of these recommendations.

These examples are taken from Airbnb’s style guide section on comments: Airbnb’s JavaScript style guide entry on comments. The code examples below have been simplified to focus on the commenting style.

Generally, adding a space to the start of your comments makes them easier to read. These examples demonstrate that.

Best Practices for Single Line Comments

For single-line comments, it’s typically recommended to put the comment on a new line above the line of code you’re explaining or referencing. If it’s not the first line of a code block put an empty line before the comment to help with clarity. Here’s a simplified example adapted from Airbnb’s style guide:

// these examples are from Airbnb's comment example // bad form because single line comment isn't on own line: const active = true; // is current tab //bad form because comment isn't separated by new line: console.log('setting the color...'); //setting the default color const defaultColor = this.color; // good form: console.log('setting the color...'); //set the default color const defaultColor = this.color;
Code language: JavaScript (javascript)

Best Practices for Multi-Line Comments

For multi-line comments, a solid recommendation is to add a * to each line intended to be part of the multi-line comment block. This more clearly signifies that the code is intended to be part of the comment block instead of a single line that may not have intentionally been included. Here’s an example:

// these examples are modified versions of Airbnb's comment examples // bad form because it uses multiple single line comments: // this function takes parameters and returns // a shape based on the parameters passed in: function makeShape(params) { // ... the code goes here return shape(); } // good form because it's clear that the comments are together: /** * this function takes parameters and returns * a shape based on the parameters passed in */ function makeShape(params) { // ... the code goes here return shape(); }
Code language: PHP (php)

These are suggestions and recommendations and doing any of the ‘bad forms’ above doesn’t make the function not work. However, it’s always good to be mindful of the best practices and community recommendations when you’re learning something new.

Debugging and Troubleshooting

Comments are essentially ignored when your code runs, so you can also use comments to turn off lines of code. This is especially useful for debugging and testing as you can isolate certain parts of your code. Remember, any commented line is ignored during compilation or run-time. This means that you can effectively disable parts of your code! You can do this line by line or disable an entire block at once. Becoming familiar with this process will greatly level up your programming skills. This process helps for debugging and troubleshooting, as well as saves time if you want to try a quick new thing without deleting your previous code. Let’s take a look at some examples.

Disabling Lines of Code

Disabling a line, or lines, of code with comments is a powerful way to troubleshoot and debug something you’ve written. Let’s work through a scenario and then an example. Let’s say that you’re creating a function and that it’s not quite working as expected. You’re receiving an error and you know that it’s in this function, but you’re not sure which line of code is breaking the program.

/* this is a contrived example * the fill() in the customRect() function breaks the code * and throws a ReferenceError * comment it out and then run the code again */ function setup() { createCanvas(400, 400); } function draw() { background(220); const myPink = color(255, 0, 100); const myGreen = color(0, 255, 100); const rectOne = customRect(myPink, 100, 100, 50, 50); const rectTwo = customRect(myGreen, 200, 200, 50, 50); } function customRect(rectColor, rectX, rectY, rectWidth, rectHeight) { fill(rgb(rectColor)); return rect(rectX, rectY, rectWidth, rectHeight) }
Code language: JavaScript (javascript)

Trying New Things

This next example is inspired by the Coding Train Code Comments video. The idea is to see whether you like a sketch between with stroke on or off. Instead of constantly deleting/undeleting the code as you try both, you can instead comment one out:

/* this example is inspired by the Coding Train video * 'Code Comments' - https://www.youtube.com/watch?v=xJcrPJuem5Q&t=12s * check that out for an overview of comments! */ function setup() { createCanvas(400, 400); } function draw() { background(255); const ellipseFillColor = fill(255, 0, 100); const ellipseStrokeColor = stroke(50, 200, 100); strokeWeight(5); // noStroke(); ellipse(200, 200, 50, 50); }
Code language: JavaScript (javascript)

Run that code into your editor and switch back and forth between commenting and uncommenting the strokeWeight(5); and noStroke(); lines. As it is in the example, there is a stroke because the line with noStroke() is a comment.

What do you think will happen if you reverse this and comment the strokeWeight(5) and uncomment the noStroke() line?


Additional Resources