aboutsummaryrefslogtreecommitdiffstats
path: root/docs/source/lang/comments.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/source/lang/comments.rst')
-rw-r--r--docs/source/lang/comments.rst67
1 files changed, 67 insertions, 0 deletions
diff --git a/docs/source/lang/comments.rst b/docs/source/lang/comments.rst
new file mode 100644
index 0000000..c5f118a
--- /dev/null
+++ b/docs/source/lang/comments.rst
@@ -0,0 +1,67 @@
+.. highlight:: cpp
+
+.. _lang-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 in RAM or Flash.
+
+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.
+
+.. _lang-comments-singleline:
+
+**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
+
+.. _lang-comments-multiline:
+
+**Multi-line comment**: Anything in between a pair of ``/*`` and ``*/``
+is a comment::
+
+ /* <-- 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 multi-line comment
+ x = 3;
+ }
+
+ // 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
+---------------
+
+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.
+
+
+
+
+.. include:: cc-attribution.txt