ISO/ IEC 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.)