By far the number one thing new developers struggle with is building their own projects from scratch. It is easy to watch a tutorial and build what they are building, but as soon as you are left on your own with a blank text editor most beginner developers freeze up and have no idea where to start. If this sounds like you then this article is perfect since I will be showing you how to fix this problem with something as simple as comments.

Break Apart Projects

Imagine you are tasked with building out a modal and are given some HTML that looks like this, but nothing else.

<button id="open-modal-btn">Open Modal</button>
<div id="overlay"></div>

<div id="modal">
  <h3>This is a modal</h3>
  <button id="close-modal-btn">Close Modal</button>
</div>

Depending on your skill level this could be a trivial task, but it is perfect for an example of how comments can be useful.

If you just jump straight into the code and start trying to make this modal then chances are you will get stuck and be unsure where to start or what to do next, especially if you have never built a modal before. This is why instead when you are presented with a problem that you are unsure of you need to think through what the steps are to complete that project without any code.

In our example we know that we have a button that we can click to open the modal and we also have an overlay that we need to show when we click on that button. We also have a close button that should close the modal and overlay when we click on it. With this in mind we can easily write out a guideline of steps to take to complete this project.

/*
  TODO: 1. Select the elements we need based on their IDs
    * modal
    * open-modal-btn
    * close-modal-btn
    * BONUS: overlay
*/

// TODO: 2. Create a click event listener for the open-modal-btn
//          that adds the class "open" to the modal
// BONUS: Also add the class "open" to the overlay

// TODO: 3. Create a click event listener for the close-modal-btn
//          that removes the class "open" from the modal
// BONUS: Also remove the class "open" from the overlay

// BONUS: Add a click event listener to the overlay that removes
//        the class "open" from the modal and the overlay

You also will notice that I broke out everything dealing with the overlay into a BONUS section. This is because the overlay is not really necessary to get the modal working at first. Generally, I find it best to do the bare minimum at first when starting a project so you can get something that works as quickly as possible. Then once you have the modal opening and closing you can work on the overlay.

Write Pseudo Code

Another great way you can use comments is to write out pseudo code for what you need to do to get a single part of your project to work. Imagine you have a project where you need to write some simple validation for a sign up form. You could just start writing the code, but you may forget things or get stuck so writing pseudo code first will help with ensuring the project gets done right.

// TODO: Create an event listener for when the form is submitted
// TODO: Create an array to store all error messages and clear any old error messages
// TODO: Define the following validation checks with appropriate error messages
//      1. Ensure the username is at least 6 characters long
//      2. Ensure the password is at least 10 characters long
//      3. Ensure the password and confirmation password match
//      4. Ensure the terms checkbox is checked
// TODO: If there are any errors then prevent the form from submitting and show the error messages

Separate Logic From Syntax

The whole idea of using comments and pseudo code is so that you can separate the logic from the syntax of the code. Learning to code is hard since you need to learn complex syntax at the same time that you are learning to solve problems in a logical way that computers can understand. Trying to do both of these at the same time is what causes most beginner programmers to fail which is why we use comments to separate those steps.

In the above examples we used comments first to split up the major tasks inside the project. This helped us to break a large project into manageable steps that we can easily conceptualize. Then in the second example we used comments to break apart an individual step into all of its logical components. This allows us to think of just the logic of the problem without worrying about the code syntax. Finally, once we have all these comments written we can come in and write the code by just doing exactly what the comments says.