In this lesson we learn how to document our code with comments, text inside the code that's ignored by the translator.
We cover both single and multi-line comments as well as the windows, linux and mac commenting shortcuts for Atom and Visual Studio Code.
Here's a table of contents of what you'll learn in this lesson:
(click on a link to skip to its section)
Let's jump right in.
What are comments
A code comment is a way for a developer to document their code.
Our code should be written cleanly and clearly enough so that it’s obvious as to what the code does. Typically we won’t need comments, but there are a few situations where it’s beneficial to do so.
- When learning programming, or a new language.
- When working as part of a group or team on a single project.
- When using external libraries.
- When working with complex code.
- When we need to temporarily remove a section of code.
- Single line comments
- Multi-line comments
Single line comments
A single line comment will only span one line. As soon as the translator encounters a line break, it will assume the comment has ended.
We write a single line comment by prefixing some text with two forward slashes ( // ).
// single line comment document.write("Hello");
A single line comment can be written on its own line, or after code.
document.write("Hello"); // we can comment after code
Writing our comments after code may sometimes be necessary, but it should be done sparingly as it can lead to confusion.
When we want to temporarily remove a line of code, we can simply comment it out by adding two forward slashes in front of it. Temporarily commenting code is useful in debugging.
The statement above will be ignored by the translator.
A multi-line comment can span one or more lines and uses open and close tags to indicate to the translator where the comment begins and ends.
The open tag is a forward slash, immediately followed by an asterisk ( /* ). The closing tag is an asterisk, immediately followed by a backslash ( */ ).
/* This is the open tag This is the close tag */ document.write("Hello");
Multi-line comments are often used as longer, more meaningful documentation, where in-depth explanation may be required.
In most cases however, programmers tend to use single line comments on multiple lines.
// Multiple single line // comments are simply // faster to write than // actual multi-line // comments document.write("Hello");
IDE Comment shortcuts
Most IDE’s provide shortcuts to comment out sections of code quickly.
In Atom, you can highlight the lines you want to comment out and press ctrl+/ or cmd+/ on your keyword. Atom will automatically comment and uncomment those lines with single line comments.
In Visual Studio Code, we have different shortcuts for single and multiline comments.
Single line: ctrl+/ or cmd+/
Multi-line: shift+alt+a or shift+option+a
Summary: Points to remember
- Comments are ignored by the translator.
- A single line comment is prefixed with two forward slashes and ends with a line break.
- A multi-line comment has an open tag ( /* ) and a close tag ( */ ) to indicate where it begins and ends.