Comments are pieces of text included in a program’s source code, but which are not executed and do not affect the program’s operation.
Their main purpose is to provide explanations, clarifications, or annotations about the written code, making it easier to understand both for the original programmer and for other developers who may read or modify the code in the future.
Comments are ignored by the compiler or interpreter, so they have no effect on the program’s execution.
Almost all languages incorporate the ability to add comments to code. They are a tool that allows developers to communicate with other programmers and leave explanatory notes within the source code.
There are two main types of comments in programming: single-line comments and block comments.
Single-Line Comments
Single-line comments are those used to add brief notes or clarifications on a single line of code.
In most programming languages, special characters are used to indicate the start of a single-line comment.
It is very common to use a double slash // in languages descended from C, such as C++, Java, or C#
// this is a single-line comment
int myVariable = 25; // it can also be placed at the end
But this is not the only case. For example, Python uses #
# this is a single-line comment
myVariable = 25 # it can also be placed at the end
While SQL or VB use the separator '
' this is a single-line comment
Dim myVariable = 25 'it can also be placed at the end
Multi-Line Comments
Multi-line comments are used when it is necessary to add more extensive explanations or comments that span multiple lines of code.
In most programming languages, multi-line comments are enclosed between a start delimiter and an end delimiter.
In languages derived from C, /* and */ are used
/*
This is a multi-line comment
It is used to provide
more extensive explanations
*/
int myVariable = 25;
But, again, this is not the only possible option. Python, for example, uses ''' both as an indicator for the start or end of a block comment
'''
This is a multi-line comment
It is used to provide
more extensive explanations
'''
myVariable = 25
On the other hand, not all languages have multi-line comments. In this case, we simply comment all the lines we want. For example, in VB
' This is a comment
' spanning multiple lines
' It is used to provide
' more extensive explanations
Dim myVariable = 25
Best Practices Tips
While comments are a very useful tool for making code easier to understand, it’s important not to overuse them.
Comments can become a problem if used excessively or if used incorrectly.
How to Use Comments
- Use comments to explain the why of the code, not the how. The code should be clear enough to explain how it works, without the need for additional comments.
- Use comments to explain parts of the code that are difficult to understand or that have significant complexity.
- Ensure that comments are accurate and up-to-date. If you change the code, make sure to update the comments as well.
Things to Avoid
- Avoid commenting code that is already obvious. Comments should provide additional information, not repeat what can already be seen in the code. That is, don’t do this:
int myVariable = 25; // assign 25 to myVariable
- Do not use comments to disable code. If you have code that doesn’t work correctly, it’s better to delete it (don’t leave fragments of commented code lying around)
- If you are going to temporarily comment out a piece of code because you are working on it (that’s fine). We all do it. But don’t leave it commented out forever, delete what you don’t need when you’re done.
