JTC1/SC22/WG14
N644
Document Number: WG14 N644/X3J11 97-007
C9X Revision Proposal
=====================
Title: Add // comments
Author: Douglas A. Gwyn
Author Affiliation: United States Army Research Laboratory
Postal Address: 801-L Cashew Court, Bel Air, MD 21014, USA
E-mail Address: gwyn@arl.mil
Telephone Number: +1-410-278-8945
Fax Number: +1-410-278-2934
Sponsor: X3J11
Date: 1997-01-03
Document History: Presented in Nashua meeting, 1995-10-16 proposal
approved in Amsterdam meeting, pending review with the
suggestion that examples and Rationale wording be added.
The present document adds examples and Rationale and
will undergo the prescribed review; it will then be
forwarded (as possibly amended by the review process)
for inclusion in the C9x draft.
Proposal Category:
__ Editorial change/non-normative contribution
__ Correction
x_ New feature
__ Addition to obsolescent feature list
__ Addition to Future Directions
__ Other (please specify) ______________________________
Area of Standard Affected:
__ Environment
__ Language
x_ Preprocessor
__ Library
__ Macro/typedef/tag name
__ Function
__ Header
__ Other (please specify) ______________________________
Prior Art: Naval Postgraduate School, Geotronics Corp., and
C++. The first two contributed implementations to
the Unix user community in the form of modifications
to the Reiser preprocessor and Ritchie C compiler
during the late 1970s. C++ supports // comments,
and they are often encountered in C code originally
written for use with a dual C/C++ implementation.
Target Audience: all C programmers
Related Documents (if any): all C++ specifications
Proposal Attached: x_ Yes __ No, but what's your interest?
Abstract: Current (C89) practice for the very useful "marginal
note" in source code is to use the only real commenting
facility in C89 as follows:
status = print( &doc_hdr ); /* could be out of paper */
Each use of this paradigm involves, in addition to the actual
comment, six characters of overhead. Multiply this by a large
number of marginal comments and it becomes evident that even a
modest reduction in overhead would benefit all C programmers.
During the early years of Unix, the book "Software Tools" by
Kernighan and Plauger was very influential; it introduced a C-
like language, Ratfor, which supported comments consisting of
# followed by arbitrary comment text to the end of the source
line. Later languages often adopted this or a similar syntax
for comments. Unfortunately, # already had conflicting
meaning in C, but in the mid-1970s the Naval Postgraduate
School made a few simple changes to the Unix C compiler and
preprocessor (which were separable at that time) to support
a similar comment style in addition to the standard /*...*/
style. They used // instead of #, but otherwise it was the
same scheme as in Ratfor. While at Geotronics Corporation
in the late 1970s, I made similar changes to the Reiser
preprocessor and Ritchie C compiler and contributed them to
USEnix, the Unix user's group. I also created a small utility
based on a finite state machine to convert //-commented source
code to standard /*...*/-commented code, to permit exporting
our nonstandard (due to use of // comments) source code to
other C compilers. Typical usage of // comments is:
status = print( &doc_hdr ); // could be out of paper
which reduces overhead by three characters per marginal
comment.
It has been reported that BCPL supported both forms of comment.
Bjarne Stroustrup was apparently aware of some of this prior
art, and adopted // comments as part of his C++ language
specification. Consequently, all C++ translators support them
and they are now widely used. Indeed, some C programmers who
use merged C/C++ translators are surprised when they port
their code to other C implementations and their // comments
are rejected as syntax errors.
Proposal: The intent is to add // comments as described above,
so that they have properties virtually identical to /*...*/
comments, apart from the difference in syntax. While
compatibility with the draft C++ standard is desirable,
differences between the standards requires that the
required changes for C9x be determined in its own context.
There are many possible ways to add // comment support, but
to ensure that they behave as much like /*...*/ comments
as possible, I suggest the following set of detailed edits:
No change to 5.1.1.2 Translation phases. (Comment still
is replaced with a space, after logical line splicing.)
No change to 6.1 Lexical elements. (Comment still is
handled specially while scanning for preprocessing tokens.)
Change in 6.1.7 Header names, Semantics from:
If the characters ', \, ", or /* occur in the
sequence between the < and > delimiters, the behavior
is undefined. Similarly, if the characters
', \, or /* occur in the sequence between the "
delimiters, the behavior is undefined.
to:
If the characters ', \, ", //, or /* occur in the
sequence between the < and > delimiters, the behavior
is undefined. Similarly, if the characters
', \, //, or /* occur in the sequence between the "
delimiters, the behavior is undefined.
(This change is debatable, since #include "//my.com/a.h"
might be better implementation-defined than undefined.)
Change in 6.1.9 Comments, from:
The contents of a comment are examined only to
identify multibyte characters and to find the
characters */ that terminate it.
[FOOTNOTE: Thus, comments do not nest.]
to:
The contents of such a comment are examined only to
identify multibyte characters and to find the
characters */ that terminate it.
[FOOTNOTE: Thus, /*...*/ comments do not nest.]
and add a new paragraph:
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 terminating
new-line character.
Add an Examples section to the end of 6.1.9 Comments:
Examples
'c//d' // four-character constant
"a//b" // four-character string literal
#include "//e" // undefined behavior
// */ // comment, not syntax error
f = g/**//h; // equivalent to f = g / h;
//\
i(); // part of two-line comment
/\
/ j(); // part of two-line comment
#define glue(x,y) x##y
glue(/,/) k(); // syntax error, not comment
/*//*/ l(); // equivalent to l();
m = n//**/o
+ p; // equivalent to m = n + p;
In the Rationale document, add to 6.1.9 Comments:
// comments were added for C9x due to their utility
and widespread existing practice, especially in
dual C/C++ translators. (C++ supports // comments.)
QUIET CHANGE
In certain unusual situations, code could have
different semantics for C89 and C9x, for example
a = b //*divisor:*/ c
+ d;
In C89 this was equivalent to
a = b / c + d;
but in C9x it is equivalent to
a = b + d;
(Another "quiet change" could occur when stringizing, but
in my opinion this does not deserve special mention.)
Also, I suggest a generic editing pass over the C9x draft
to change all genuinely marginal comments to use // style.
(Use of "/* ... */" to represent elided source test should
not be changed, and there are some other embedded /*...*/
comments, particularly in the preprocessor section, that
should not be changed since they are essential to the
functioning of the examples.)