From 754bbf7a25a8dda49b5d08ef0d0443bbf5af0e36 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Sun, 7 Apr 2024 13:41:34 -0500 Subject: new repository --- devdocs/c/comment.html | 86 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 devdocs/c/comment.html (limited to 'devdocs/c/comment.html') diff --git a/devdocs/c/comment.html b/devdocs/c/comment.html new file mode 100644 index 00000000..07ac5f27 --- /dev/null +++ b/devdocs/c/comment.html @@ -0,0 +1,86 @@ +

Comments

Comments serve as a sort of in-code documentation. When inserted into a program, they are effectively ignored by the compiler; they are solely intended to be used as notes by the humans that read source code.

+

Syntax

+ + +
/* comment */ (1)
// comment (2) (since C99)
+1) Often known as "C-style" or "multi-line" comments.
+2) Often known as "C++-style" or "single-line" comments.

All comments are removed from the program at translation phase 3 by replacing each comment with a single whitespace character.

+

C-style

C-style comments are usually used to comment large blocks of text or small fragments of code; however, they can be used to comment single lines. To insert text as a C-style comment, simply surround the text with /* and */. C-style comments tell the compiler to ignore all content between /* and */. Although it is not part of the C standard, /** and **/ are often used to indicate documentation blocks; this is legal because the second asterisk is simply treated as part of the comment.

+

Except within a character constant, a string literal, or a comment, the characters /* introduce a comment. The contents of such a comment are examined only to identify multibyte characters and to find the characters */ that terminate the comment. C-style comments cannot be nested.

+ + +

C++-style

C++-style comments are usually used to comment single lines of text or code; however, they can be placed together to form multi-line comments. To insert text as a C++-style comment, simply precede the text with // and follow the text with the new line character. C++-style comments tell the compiler to ignore all content between // and a new line.

+

Except within a character constant, a string literal, or a comment, the characters // introduce a comment that includes all multibyte characters up to, but not including, the next new-line character. The contents of such a comment are examined only to identify multibyte characters and to find the new-line character that terminates the comment. C++-style comments can be nested:

+
//  y = f(x);   // invoke algorithm

A C-style comment may appear within a C++-style comment:

+
//  y = f(x);   /* invoke algorithm */

A C++-style comment may appear within a C-style comment; this is a mechanism for excluding a small block of source code:

+
/*
+    y = f(x);   // invoke algorithms
+    z = g(x);
+*/
 (since C99)

Notes

Because comments are removed before the preprocessor stage, a macro cannot be used to form a comment and an unterminated C-style comment doesn't spill over from an #include'd file.

+
/* An attempt to use a macro to form a comment. */
+/* But, a space replaces characters "//".       */
+#ifndef DEBUG
+    #define PRINTF //
+#else
+    #define PRINTF printf
+#endif
+...  
+PRINTF("Error in file %s at line %i\n", __FILE__, __LINE__);

Besides commenting out, other mechanisms used for source code exclusion are:

+
#if 0
+    puts("this will not be compiled");
+    /* no conflict with C-style comments */
+    // no conflict with C++-style comments
+#endif

and

+
if(0) {
+    puts("this will be compiled but not be executed");
+    /* no conflict with C-style comments */
+    // no conflict with C++-style comments
+}

The introduction of // comments in C99 was a breaking change in some rare circumstances:

+
a = b //*divisor:*/ c
++ d; /* C89 compiles a = b / c + d;
+        C99 compiles a = b + d; */

Example

#include <stdio.h>
+/*
+C-style comments can contain
+multiple lines.
+*/
+ 
+/* Or, just one line. */
+ 
+// C++-style comments can comment one line.
+ 
+// Or, they can
+// be strung together.
+ 
+int main(void)
+{
+  // The below code won't be run
+  // puts("Hello");
+ 
+  // The below code will be run
+  puts("World");
+ 
+  // A note regarding backslash + newline.
+  // Despite belonging to translation phase 2 (vs phase 3 for comments),
+  // '\' still determines which portion of the source code is considered
+  // as 'comments':
+  // This comment will be promoted to the next line \
+  puts("Won't be run"); // may issue a warning "multi-line comment"
+  puts("Hello, again");
+}

Output:

+
World
+Hello, again

References

See also

+
C++ documentation for Comments
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/comment +

+
-- cgit v1.2.3