From 3b9dee4a771eacc915a248ad91a26063fcc2e571 Mon Sep 17 00:00:00 2001 From: Matthias Felleisen Date: Tue, 18 Sep 2012 14:00:07 -0400 Subject: [PATCH] [Style] Rouben Rostamian's request to elaborate on block comments --- .../scribblings/style/acknowledgment.scrbl | 2 ++ collects/scribblings/style/constructs.scrbl | 36 +++++++++---------- 2 files changed, 18 insertions(+), 20 deletions(-) diff --git a/collects/scribblings/style/acknowledgment.scrbl b/collects/scribblings/style/acknowledgment.scrbl index ea748b20b3..67bfcef938 100644 --- a/collects/scribblings/style/acknowledgment.scrbl +++ b/collects/scribblings/style/acknowledgment.scrbl @@ -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 diff --git a/collects/scribblings/style/constructs.scrbl b/collects/scribblings/style/constructs.scrbl index 80611dfe43..8db2848eff 100644 --- a/collects/scribblings/style/constructs.scrbl +++ b/collects/scribblings/style/constructs.scrbl @@ -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}