suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[Style] Rouben Rostamian's request to elaborate on block comments

Browse Source
This commit is contained in:
Matthias Felleisen 2012-09-18 14:00:07 -04:00 committed by Eli Barzilay
parent b8cef59702
commit 3b9dee4a77
2 changed files with 18 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
collects/scribblings/style/acknowledgment.scrbl
View File

@ -7,3 +7,5 @@ their own coding experience, the first author also conducted focus sessions
with the members of PLT and these sessions produced many insights about
coding style. Jacob Matthews took the time to write up his thoughts on
testing, and they are much appreciated.
@;Rouben Rostamian

36
collects/scribblings/style/constructs.scrbl
View File

@ -25,26 +25,22 @@ headers from section headers.
In addition to ``;'', we have two other mechanisms for commenting code:
``#|...|#'' for blocks and ``#;'' to comment out an expression.
In rare cases there might be a more substantial piece of text or code, and
in that case the block comment style can be more convenient than
semicolons. Another use of block comments is for code samples to be
copied and pasted into a file. Either way, block comments are not used
for single-line comments.
Expression comments---``#;''---apply to the following S-expression. This
makes them a useful tool for debugging. They can even be composed in
interesting ways with other comments, for example, ``#;#;'' will comment
two expressions, and a line with just ``;#;'' gives you a single-character
``toggle'' for the expression that starts on the next line. But on the
flip side, lots tools don't process them properly---treating them instead
as a ``#'' followed by a commented line. For example, in DrRacket
S-expression comments are ignored when it comes to syntax coloring, which
makes it easy to miss them. In Emacs, the commented text is colored like a
comment and treated as text, which makes it difficult to edit as code.
The bottom line here is that ``#;'' comments are useful for debugging, but
try to avoid leaving them in committed code. If you really want to use
``#;'', clarify their use with a line comment (``;'').
@defterm{Block comments} are for those rare cases when an entire block of
definitions and/or expressions must be commented out at once.
@defterm{Expression comments}---``#;''---apply to the following
S-expression. This makes them a useful tool for debugging. They can even
be composed in interesting ways with other comments, for example, ``#;#;''
will comment two expressions, and a line with just ``;#;'' gives you a
single-character ``toggle'' for the expression that starts on the next
line. But on the flip side, lots tools don't process them
properly---treating them instead as a ``#'' followed by a commented line.
For example, in DrRacket S-expression comments are ignored when it comes
to syntax coloring, which makes it easy to miss them. In Emacs, the
commented text is colored like a comment and treated as text, which makes
it difficult to edit as code. The bottom line here is that ``#;''
comments are useful for debugging, but try to avoid leaving them in
committed code. If you really want to use ``#;'', clarify their use with
a line comment (``;'').
@; -----------------------------------------------------------------------------
@section{Definitions}