The first concern in programming is usually how the machine reads the code interprets it. Indeed, taking into account the people who will read and work with the code is very important. Whether you should be working with a team or on your own, learning how to comment and structure your code for readers appropriately will be needed.
Comments are annotations in a program's source code that the interpreter ignores and thus do not affect the code's real result. Comments can often be extremely helpful in understanding the purpose of the part of your code.
As a developer, looking deeper into the code written by anyone else that has not been appropriately commented can be annoying, and it is incredibly easy to forget what your code actually intended when you are no longer involved in that project. If you comment your code properly on the right time, it will become a good programming habit, and you will avoid future misunderstandings.
There is a famous cliché that “Good code is self-documenting.” And when you start a new project, you should think about the clarification and documentation of your code, which can be done by comments.
- Single-line comments
- Multi-line comments
Single-line Comments¶Two forward slashes (//) are used to write single-line comments:
// I am a comment.
See this example which uses a single-line comment before each code line:
Single-line comments are considered to be inline comments when they appear at the end of a line of code.
For quick annotation on small, specific snippets of content, inline comments can be used. Since the comment should relate only to the exact line on which it is written, it is the most apparent type of comment.
Although inline comments may be useful, they should be used carefully. Code covered in an abundance of inline comments will easily become messy, making it hard to read.
Multi-line comments, widely known as block comments, start with /* and end with */. If you know CSS, then you're already familiar with block-level comments.
/* I am a multi-line comment */
See an example that uses a multi-line comment (a comment block) to simplify the code:
Note that it is most common to use single-line comments. Block comments are often used for formal documentation. And they will sometimes include details about the programming file, including the name, version, and the author of the script.
Use Comments to Prevent Execution When Testing Alternative Code¶
Comments can be used to prevent code execution for testing and debugging reasons easily and quickly. It's called "commenting out the code."
Adding // in front of a code line changes the code lines from an executable line to comment.
When there is an error in a specific code that you have written, commenting on sections will prevent them from running, and it can be useful to identify the source of the problem. To test different results, you can also use it to switch between code.
See an example that uses the // to prevent the execution of one of the code lines:
Based on the size of the section being toggled, both single-line comments and block comments may be used to comment out the code.
Commenting out code can be useful when working out a project's logic as you determine where bugs are or assess the lines of code which provide the most utility.
Don't regret your time to drop regular annotation on complicated sections of code will be an advantage in the future, making it easier for you and your colleagues to understand the purpose of the code you've written.