loader

Adding Notes to Your JavaScript Code

Adding Notes to Your JavaScript Code

Introduction:

When we write code, we often focus on making sure the computer understands it. But it’s just as important to think about the people who will read and work with the code. Whether you’re part of a team or working solo, you need to learn how to add comments and organize your code so it’s easy for humans to understand.

Comments are notes you write in your code that the computer ignores when it runs the program. So, they don’t affect what the program does or shows. But comments are super useful for explaining what your code is meant to do. They help you and others understand the purpose of different parts of your code.

Imagine you’re trying to understand code written by someone else, but they didn’t explain what it does. That can be really frustrating! Similarly, even when you write your own code, you might forget what it does later on if you don’t explain it. That’s why it’s important to add comments to your code early on. It helps you and others understand what the code is doing, and it’s a good habit to develop as a programmer.

How to Write Comments in JavaScript

Let’s learn about the two ways to write comments in JavaScript.

For comments that only need one line, you use two forward slashes (//):

// This is a comment
Copy

When you use // in JavaScript, anything after it on the same line is ignored by the computer. This is great for short comments.

For longer comments that can span multiple lines, you use /* to start and */ to end. It’s like how you write comments in CSS if you’re familiar with that. These are called block comments.

/* This is
a comment */

Copy

In both single-line and multi-line comments, everything you write between the opening and closing tags is ignored by the computer.

You usually write comments above the code they’re meant to explain. Let’s see how this works with a simple “Hello, World!” example:

// Print "Hello, World!" to the console
console.log("Hello, World!");
Copy

When writing comments, make sure they are indented at the same level as the code directly beneath them.

// Initialize a function
function alphabetizeOceans() {
	// Define oceans variable as a list of strings
	const oceans = ["Pacific", "Atlantic", "Indian", "Antarctic", "Arctic"];

	// Print alphabetized array to the console
	console.log(oceans.sort());
}

Copy

Remember, comments are like little notes that help explain what the code does. It’s important to keep them up-to-date just like the rest of your code. Outdated comments can cause confusion, so make sure to check and update them regularly.

Quick Tips for Adding Comments to Your Code

When you see a comment written at the end of a line of code, it’s called an ‘inline comment’. It’s just a quick note right next to the code to explain what it does.

let x = 99;    // assign numerical value to x
let y = x + 2; // assign the sum of x + 2 to y
Copy

Inline comments are short notes you write on one line of code to explain what it does. They’re handy for adding quick explanations exactly where they’re needed. Just remember, once you start an inline comment with two slashes (//), everything after that on the same line is just a comment and not part of the code.

for (let i = 0; i === 10; i++) // for loop that runs ten times {
	// Running this code results in a syntax error
}
Copy

While inline comments can be helpful, it’s best not to use too many of them. If you have too many, your code might look messy and be hard to understand.

Exploring Block Comments

Block-level comments, also known as multi-line comments, are like little notes you write to yourself or others to explain what a section of code does. You’ll usually find them at the beginning of a file or right before a tricky part of the code. They’re helpful for understanding what’s going on in the code!

/* Initialize and invoke a the greetUser function
to assign user's name to a constant and print out
a greeting. */

function greetUser() {
	const name = prompt("What is your name?");
	console.log("Hello ," + name + "! How are you?");
}

greetUser();
Copy

Sometimes, you might come across a different kind of block comment that starts with /** and has asterisks scattered on the left side of the comment box. It’s just another way to write comments in your code!

/**
 * Initialize constant with an array of strings.
 * Loop through each item in the array and print
 * it to the console.
 */

const seaCreatures = ["Shark", "Fish", "Octopus"];

for (const seaCreature of seaCreatures) {
  console.log(seaCreature);
}
Copy

Every now and then, you might see a type of comment that starts with /** and has stars scattered on the left side. It might also contain extra information about the code file, such as its name, version, and who created it.

If you’re just starting out with JavaScript, it’s perfectly fine to write lots of comments to help you understand your code better. But as you improve, you’ll start thinking more about why you’re writing the code, not just how it works.

Using Comments to Test Code

Comments can also be used to quickly stop parts of your code from running when you’re testing or fixing problems. This is called “commenting out code”.

If you have a mistake in your code, you can comment out sections to stop them from running. This can help you find where the problem is. You can also use it to switch between different bits of code to see what happens.

// Function to add two numbers
function addTwoNumbers(x, y) {
  let sum = x + y;
  return sum;
}

// Function to multiply two numbers
function multiplyTwoNumbers(x, y) {
  let product = x * y;
  return product;
}

/* In this example, we're commenting out the addTwoNumbers
function, therefore preventing it from executing. Only the
multiplyTwoNumbers function will run */

// addTwoNumbers(3, 5);
multiplyTwoNumbers(5, 9);
Copy

You can use both short comments and longer block comments to turn off code. It depends on how big the part of the code you want to stop is.

(Notes: When you’re testing your code, it’s okay to comment out parts you don’t want to run. But remember, don’t leave those commented-out parts in your final code when you’re done testing.)

When you’re figuring out how your program should work, it can be useful to comment out parts of the code. This helps you find any mistakes and see which lines are most important.

Conclusion:

In JavaScript, your code is read not only by computers but also by other programmers, including yourself in the future. It’s important to add clear notes to tricky parts of your code. This will help you and others understand what your code is meant to do. Remember, taking a little extra time to do this will make life easier for everyone working on the code!

Remember, adding comments can save you time and frustration later on. So, don’t forget to leave helpful notes for yourself and your teammates!

image

A cloud for entire journey

Bring your team together. No contracts, no commitments.

image

Copyright ©2023 Design & Developed by Cloudtopiaa