Introduction

Comments that appear in a sketch are ignored by the computer and are solely for the sake of the humans reading the sketch. Comments play an important role in aiding those who are trying to understand what a sketch does. Often, these comments provide this aid to the person who wrote the sketch in the first place. Computer code can be rather difficult to understand, which is why comments prove so useful.

There are two ways to include comments in your code. The first uses two backslashes “//”. The text between these backslashes and the end of the line is ignored, i.e., it is treated as a comment. Any text on the line in front of the backslashes is not a comment. The following line of code shows an executable statement (where a value is assigned to the variable x) followed by a comment.

                  x = 134 + 47;  // x is assigned the sum of 134 and 47.
                

Typically, we don't want the comments to be a mere restatement of what the computer code already tells us. The comment above isn't particularly useful because it is already pretty easy to understand what this statement is doing. As you read and write more code, you will eventually gain a better understanding of what does and does not constitute a useful comment.

The other way to comment code is by enclosing the comment in delimiters that mark the beginning and end of the comment. The opening delimiter is “ /*” while the closing delimiter is “*/ ”. Using this form of commenting, we can place comments anywhere in the code, even within an expression (as is illustrated below). Within the “/*” and “*/”delimiters, comments can also span multiple lines. The following example starts with a comment that spans one line. This is followed, on line 2, by an executable statement and then, on lines 4 through 9, there is a multi-line comment. On lines 10 through 12, there is an expression with comments embedded in it. This expression spans three lines but is equivalent to writing a = b + c + d; . The comments in lines 10 through 12 could have been written using two backslashes instead of the “/*” and “*/ ”, i.e., one could replace “/*” on these lines with “//” and omit “*/”.

                  /* x is assigned the sum of 134 and 47. */
                  x = 134 + 47;
                  
                  /*
                     This is a multi-line comment.  The computer ignores all this.

                     The following is a single expression but it spans multiple lines
                     and has comments embedded in it.
                  */
                  a = b + /* b is the first variable in this sum. */
                      c + /* c is the second variable in this sum. */
                      d;  /* d is the third variable in this sum. */
                

Finally, the following statement appears on a single line and has comments completely embedded within it. In this case, these comments could not be replaced with the double-backslash form of a comment (because those double-backslash comments extend to the end of the line and here the last thing on the line is part of the statement). But we should note that just because you can do something doesn't mean you should! Embedding comments like this (directly in an executable statement) is not a good idea; it makes the code quite hard to read.

                  z = /* Bad comment! */ 23 + /* Awkward! */ 92;