diff options
Diffstat (limited to 'docs/source/arduino/comments.rst')
| -rw-r--r-- | docs/source/arduino/comments.rst | 69 |
1 files changed, 42 insertions, 27 deletions
diff --git a/docs/source/arduino/comments.rst b/docs/source/arduino/comments.rst index 189ead5..3aeb37f 100644 --- a/docs/source/arduino/comments.rst +++ b/docs/source/arduino/comments.rst @@ -1,45 +1,60 @@ +.. highlight:: cpp + .. _arduino-comments: Comments ======== -Comments are lines in the program that are used to inform yourself -or others about the way the program works. They are ignored by the -compiler, and not exported to the processor, so they don't take up -any space on the Atmega chip. - - +Comments are lines in the program that are used to inform yourself or +others about the way the program works. They are ignored by the +compiler, and not exported to the processor, so they don't take up any +space in RAM or Flash. -Comments only purpose are to help you understand (or remember) how -your program works or to inform others how your program works. -There are two different ways of marking a line as a comment: +One use for comments is to help you understand (or remember) how your +program works, or to inform others how your program works. There are +two different ways of making comments. +**Single line comment**: Anything following two slashes, ``//``, until +the end of the line, is a comment:: + x = 5; // the rest of this line is a comment -Example -------- - -:: - - x = 5; // This is a single line comment. Anything after the slashes is a comment - // to the end of the line +**Multi-line comment**: Anything in between a pair of ``/*`` and ``*/`` +is a comment:: - /* this is multiline comment - use it to comment out whole blocks of code + /* <-- a slash-star begins a multi-line comment + + all of this in the multi-line comment - you can use it to comment + out whole blocks of code - if (gwb == 0){ // single line comment is OK inside a multiline comment - x = 3; /* but not another multiline comment - this is invalid */ + if (gwb == 0){ // single line comment is OK inside a multi-line comment + x = 3; } - // don't forget the "closing" comment - they have to be balanced! + + // don't forget the "closing" star-slash - they have to be balanced: */ +Note that it's okay to use single-line comments within a multi-line +comment, but you can't use multi-line comments within a multi-line +comment. Here's an example:: + + /* ok, i started a multi-line comment + + x = 3; /* this next star-slash ENDS the multi-line comment: */ + + x = 4; // this line is outside of the multi-line comment + + // next line is also outside of the comment, and causes a compile error: + */ +Programming Tip +--------------- -**Tip** -When experimenting with code, "commenting out" parts of your -program is a convenient way to remove lines that may be buggy. This -leaves the lines in the code, but turns them into comments, so the -compiler just ignores them. This can be especially useful when -trying to locate a problem, or when a program refuses to compile -and the compiler error is cryptic or unhelpful. +When experimenting with code, "commenting out" parts of your program +is a convenient way to remove lines that may be buggy. This leaves +the lines in the code, but turns them into comments, so the compiler +just ignores them. This can be especially useful when trying to locate +a problem, or when a program refuses to compile and the compiler error +is cryptic or unhelpful. |