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.)