Code is the text that is interpreted by the computer to perform the desired action according to defined instructions. Code is not easily readable by humans; therefore, the comments are useful to annotate or describe in human terms the purpose of a block of code (Fig.92). Comments are ignored by compilers and interpreters. As comments are ignored by the interpreters, programmers usually use the comment tag for testing purposes to ignore a portion of code while running the program (Fig.93).
Fig.92 demonstrates the use of comments to:
- Document a section or block of code.
- Annotate a specific operation or instruction.
Note:
There are two ways to add comments to your code, multi-line, and single-line comments. To write a multi-line comment, use the slash and asterisk symbol and for the single-line comment, start it with a double slash.
The multi-line comments block starts with slash and asterisk (line 39) and ends with asterisk slash (line 42).
Single-line comments start with a double slash. Note that single-line comments do not require an ending tag.
Why and when to use comments?
Comments are annotations, or descriptions, for programmers and are ignored by the compiler. As comments are ignored by the compiler and interpreter, comments are not strictly required to run the program. The use of comments in programming is a best practice to document and explain your code and make it more readable to you later in time when you need to get back to it for an update or a new implementation. It is also useful when you share your code with other people and provide a more readable code.
Comments are worthwhile for:
- Collaboration: When working with a team of programmers, comments can help other participants to understand your code.
- Complex algorithm: Comments help to understand the code.
- Big project: In a big programming project with thousands of lines of code, comments help to structure and organize your code into sections which are described with comments for clarity.
- Future use: When you need to modify your code at a later time, comments might help you to bring up your memory on how the code works.
- Code reusability: A while documented code can be reused in another project.
Coding tips:
It is recommended to provide a comment that explains the purpose and the use of each block of code to bring clarity to your project:
- Provide the name and purpose of your block of code.
- Explain what information is calculated.
- Define the parameters that are required and how to use them.
- And finally, provide a brief description of how the block of code operates.
