[Style] robby's reactions

collects/scribblings/style/correct-maintain-speed.scrbl

@@ -21,7 +21,7 @@ three points. Specifically, it spells out suggestions @emph{that you can
 check} and that everyone else can check.
 
 @; -----------------------------------------------------------------------------
-@section{Correctness}
+@section[#:tag "correctness"]{Correctness}
 
 @nested[#:style 'inset]{I have bug reports, therefore I exist. -- Matthias,
 watching Matthew, Robby, Shriram and others create the original code base}
@@ -96,8 +96,9 @@ In order to document code, refer to the
  and make use of other useful cross-references.
 
 Code comprehension also requires adherence to basic elements of style and
- some internal documentation. The rest of this document is about these
- elements of style, including some suggestions on internal documentation.
+ some internal documentation. The rest of this document is mostly about
+ these elements of style, including some suggestions on internal
+ documentation.
 
 @; -----------------------------------------------------------------------------
 @section{Speed}
@@ -131,4 +132,5 @@ Stress tests don't normally have an expected output, so they never
  improvement, just document the weakness in the external library and move
  on.
 
-We are not perfectionist. We produce reasonable software.
+We are not perfectionists. We produce reasonable software.
+

collects/scribblings/style/size.scrbl

@@ -11,4 +11,6 @@ Keep functions small. Keep classes small. Keep units small. Keep modules small.
 
 Anytime a unit of code looks incomprehensible, it is probably too
 large. Break it up into smaller units. To bring across what these smaller
-units compute, implement or serve, use meaningful names.
+units compute, implement or serve, use meaningful names. Conversely, if you
+can't come up with a good name for such units, you are probably looking at
+the wrong kind of division; consider alternatives.

collects/scribblings/style/some-performance.scrbl

@@ -0,0 +1,17 @@
+#lang scribble/base
+
+@(require "shared.rkt")
+
+@; -----------------------------------------------------------------------------
+@(define rurl "http://docs.racket-lang.org/reference/index.html?q=racket/base")
+@(define (rkt) @hyperlink[rurl]{racket})
+@(define (rkt/base) @hyperlink[rurl]{racket/base})
+
+@title{Some Performance Hints}
+
+Use @rkt/base[] instead of @rkt[] for any library that others may use
+ eventually. For all other modules, use @rkt[].
+
+The @rkt/base[] language loads significantly faster than the @rkt[]
+language and is also significnatly smaller. Conversely, it is much more
+convenient to program with @rkt[] than @rkt/base[].

collects/scribblings/style/style.scrbl

@@ -3,12 +3,12 @@
 @(require "shared.rkt")
 
 @title{How to Program Racket}
-@author{Matthias Felleisen, Matthew Flatt}
+@author{Matthias Felleisen, Matthew Flatt, Robby Findler, Jay McCarthy}
 
 @; -----------------------------------------------------------------------------
 
 Since 1995 PLT has grown from a handful of people who worked on/with the
- repository to three dozen and more. In addition, Racekt is an open source
+ repository to three dozen and more. In addition, Racket is an open source
  project, meaning other people study the code in the repository and use it
  as an implicit guide to Racket programming. To manage the growth of the PLT
  developer basis and to showcase good Racket coding, every contribution
@@ -33,5 +33,6 @@ This document spells out these criteria, and it is also a call for
 @; -----------------------------------------------------------------------------
 
 @include-section["correct-maintain-speed.scrbl"]
+@include-section["some-performance.scrbl"]
 @include-section["size.scrbl"]
 @include-section["textual.scrbl"]

collects/scribblings/style/textual.scrbl

@@ -11,7 +11,10 @@
 Simple textual conventions help eyes find pieces of code quickly. Here are
 some of those that are easy to check---some automatically and some
 manually. If you find yourself editing a file that violates some of the
-constraints below, edit it into the proper shape.
+constraints below, edit it into the proper
+shape. @margin-note{@bold{Warning}: On rare occasion a unit test may depend
+on the indentation of a file. This is extremely rare but you should be
+aware of it.}
 
 @; -----------------------------------------------------------------------------
 @section{Indentation}
@@ -21,7 +24,9 @@ on. So use DrRacket's indentation style. Here is what this means.
 @nested[#:style 'inset]{
  For every file in the repository, DrRacket's "indent all" functions leaves
  the file alone.}
-That's all there is to it.
+That's all there is to it. @margin-note{See @secref{correctness}. If you
+really believe that DrRacket indents some construct improperly, submit a
+bug report. When the bug report is closed, the discussion is finished.}
 
 If you prefer to use some other editor (emacs, vi/m, etc), program it so
 that it follows DrRacket's indentation style.