Line comments

From Successor ML

Jump to: navigation, search

1. Introduction --- Several writers commenting on best practices in software development stress the superiority of line comments over bracketed comments. Standard ML lacks line comments. This RFC recommends that line comments begin with '#' preceded and followed by whitespace (where both newline and (start|end)-of-file are interpreted as whitespace) and end, of course, with #"\n".

2. Motivation and examples --- A recent article by Bertrand Meyers reminds us that line comments are more readable, and more likely to be read, than bracketed comments. Another virtue, for the ML family of languages with nested bracketed comments, as that line comments offer a place to include pragmas without interfering with any other aspects of the language.

   # This is a comment
   #but this is not, and
   ## (. is a symbolic identifier, as is .)
   #$          #  -- etc, but this # is part is an end-of-line comment.

Of all the possible ways of denoting line comment beginnings, the hashmark here proposed has probably the widest usage in existing practice, for example in virtually all shell scripts, Perl, Python, Ruby &tc. It also stands out well visually and is one of the very few single ascii characters which can be adapted to this purpose without doing considerable violence to SML.

(Minor aside: This choice would also harmonize well with any eventual desire to support the the POSIX-world "shebang" ("#!/usr/bin/sml") convention.)

3. Assumptions --- None.

4. Formal syntax --- Except within string constants, the symbolic identifier hashmark (#"#") when surrounded by whitespace is reserved for the purpose of beginning line comments. The line comment extends to the next end of line -- i.e., #"\n" or end-of-file.
Described in stages of lexing:

  1. Replace line comments by #"\n";
  2. Replace bracketed comments by #" ";
  3. Lex the actual program text tokens.

5. Formal static semantics -- None.

6. Formal dynamic semantics -- None.

7. Interactions with previous proposals and other language features: No formal interaction, but arguably some small risk of confusion with #2 and #field style record selection syntax.

8. Porting issues --- minimal to non-existent.

9. Implementation issues --- This change requires a small modification to lexers.

Delta to The Definition: On page 4, add subsection 2.3.1 entitled Bracketed Comments before current paragraph of section 2.3. After the current paragraph, add subsecction 2.3.2 entitled Line Comments. Follow this by the text of 4. above after the phrase 'Formal Syntax'.

Personal tools