[Style] fixing typos, added Robby's commit bomb prose

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

@@ -4,8 +4,8 @@
 
 @title[#:tag "correct-maintain-speed"]{Basic Facts of Life}
 
-@nested[#:style 'inset]{ Favor readers over writers.
+@nested[#:style 'inset]{ @italic{Favor readers over writers.}
- --- Yaron Minsky, JaneStreet, 2010 at Northeastern}
+ --- Yaron Minsky, JaneStreet, 2010 at NEU/CCS}
 
 Write code that is correct; maintainable; and fast. The ordering of these
  adjectives is critical: correct is more important than maintainable;
@@ -14,10 +14,9 @@ Write code that is correct; maintainable; and fast. The ordering of these
 
 @margin-note{This ordering is occasionally wrong. For example, we could
  avoid IEEE floating point numbers nearly all of the time. To make this
- precise, the @scheme[sqrt] function could return a rational number whose
+ precise, the Racket @scheme[sqrt] function could return a rational number
- value was the same as the IEEE float result.  We don't do such silly
+ close to the IEEE float result.  We don't do such silly things, however,
- things, however, because we have decided to value speed over precision in
+ because we have decided to value speed over precision in this context.}
- this context.}
 
 Code is correct.
 
@@ -32,11 +31,11 @@ check} and that everyone else can check.
 @; -----------------------------------------------------------------------------
 @section[#:tag "correctness"]{Correctness}
 
-@nested[#:style 'inset]{I have bug reports, therefore I exist. -- Matthias,
+@nested[#:style 'inset]{@italic{I have bug reports, therefore I exist.} -- Matthias,
 watching Matthew, Robby, Shriram and others create the original code base}
 
-@nested[#:style 'inset]{It is the way we choose to fight our bugs that
+@nested[#:style 'inset]{@italic{It is the way we choose to fight our bugs that
- determines our character, not their presence or absence. -- Robby, in response}
+ determines our character, not their presence or absence.} -- Robby, in response}
 
 Complete correctness is a perfectionist goal beyond the reach of PLT.  All
  software has mistakes. If they are unknown, the software isn't being
@@ -54,20 +53,20 @@ When you debug, formulate a test case first. Put it into the test suite for
  the component so the mistake will never be accidentally re-introduced.
  Second, modify the code to fix the mistake. Do this second to be sure you
  didn't introduce a mistake in your tests; it is all too easy to think
- you've fixed a mistake when in reality your new test just doesn't properly
+ you have fixed a mistake when in reality your new test just doesn't properly
  reveal the old mistake.  Third, re-run the test suite to ensure that the
  mistake is fixed and no existing tests fail.
 
-Create test suites. Editing code without an existing test suite is like
+Editing code without an existing test suite is like flying blind.  If there
- flying blind.  If there is no existing test suite, you have no idea
+ is no existing test suite, you have no idea whether changes are
- whether changes are introducing any new mistakes or breaking intended
+ introducing any new mistakes or breaking intended functionality.  Make a
- functionality.  Make a reasonable effort to put in a test case or two for
+ reasonable effort to put in a test case or two for the specific
- the specific functionality that you're adding or modifying.  If there is
+ functionality that you are adding or modifying.  If there is no test suite
- no test suite and you aren't sure how to build one, then ask, see what
+ and you aren't sure how to build one, then ask, see what responses you
- responses you get, and go from there.  In the special case that you found
+ get, and go from there.  In the special case that you found a mistake and
- a mistake and are fixing it, there should be a way to observe that mistake
+ are fixing it, there should be a way to observe that mistake and you
- and you should be able to turn that into a test case. If you cannot, you
+ should be able to turn that into a test case. If you cannot, you have a
- have a few options:
+ few options:
 
 @itemlist[#:style 'ordered
 
@@ -81,7 +80,7 @@ Create test suites. Editing code without an existing test suite is like
     slides to enable an automated test suite.}
 ]
  As we slowly increase the number of tests across the system, this problem
- will go away for future generations.
+ will go away for future generations of maintainers.
 
 @; -----------------------------------------------------------------------------
 @section{Maintenance}
@@ -94,7 +93,7 @@ Comprehensible code is maintainable.  Maintainable code must be easily
 Code is comprehensible when you can understand its external purpose. To
  this end, code must come with external documentation. Released code must
  have documentation. A change to the external behavior of code must induce
- a simultaneous change to its documentation---"simultaneous" means that the
+ a simultaneous change to its documentation---``simultaneous'' means that the
  two changes are in the same commit to the code base.
 
 Without adherence to basic elements of style and some internal
@@ -106,10 +105,10 @@ Readability is not the same as code with documentation, but documentation
  is a part of it all.  For style rules on documenting code, refer to the
  @hyperlink["http://docs.racket-lang.org/scribble/how-to-doc.html#%28part._reference-style%29"]{style
  guide} in the Scribble manual.  Ideally documentation comes in two parts:
- a "Guide" section, which explains the purpose and suggests use cases, and
+ a ``Guide'' section, which explains the purpose and suggests use cases, and
- a traditional "Reference" section, which presents the minutae.  Also
+ a traditional ``Reference'' section, which presents the minutae.  Also
  consider adding examples for each function and construct in your
- "Reference" section.  Finally, ensure you have all the correct
+ ``Reference'' section.  Finally, ensure you have all the correct
  @tt{for-label} @tt{require}s and make use of other useful
  cross-references.
 
@@ -131,7 +130,7 @@ It is especially the goal for all pieces of the code base that are reused
  elsewhere. Write them using @rkt/base[] so that they don't affect the
  load-time for scripts. See the next section.
 
-As with correctness, performance demands some "testing". At a minimum,
+As with correctness, performance demands some ``testing.'' At a minimum,
  exercise your code on some reasonably large inputs. Add a file to the test
  suite that runs large inputs regularly. For example, a regular test suite
  for a Universe display deals with a 50 x 50 display window; one of its
@@ -141,27 +140,17 @@ As with correctness, performance demands some "testing". At a minimum,
  ensures that it deals correctly with enqueue and dequeue for small queues,
  including empty ones; a stress test suite for the same library would run
  the queue operations on a variety of queue sizes, including very large
- queues of say 10,000 elements.
+ queues of say tens of thousands elements.
 
 Stress tests don't normally have an expected output, so they never
- "pass". The practice of writing stress tests exposes implementation flaws
+ pass. The practice of writing stress tests exposes implementation flaws or
- or provides comparative data to be used when choosing between two
+ provides comparative data to be used when choosing between two APIs. Just
- APIs. Just writing them and keeping them around reminds us that things can
+ writing them and keeping them around reminds us that things can go bad and
- go bad and we can detect when performance degrades through some other
+ we can detect when performance degrades through some other door. Most
- door. Most importantly, a stress test may reveal that your code isn't
+ importantly, a stress test may reveal that your code isn't implementing an
- implementing an algorithm with the expected O(.) running time. Finding out
+ algorithm with the expected O(.) running time. Finding out that much alone
- that much alone is useful. If you can't think of an improvement, just
+ is useful. If you can't think of an improvement, just document the
- document the weakness in the external library and move on.
+ weakness in the external library and move on.
 
 And as you read on, keep in mind that we are not perfectionists. We produce
  reasonable software.
-
-@section{Commit}
-
-So what is the major lesson of this section? When you fix a bug, make sure
- to commit (1) the code delta, (2) the new test case, and (3) the revised
- docs (if applicable) in one batch. If the creation of a single commit is
- too complex of if you wish to factor out one of the commits, please push
- all pieces at once. That way the code base is always in a state where
- code, tests, and documentation are in sync, and readers of commit messages
- can evaluate changes completely.

collects/scribblings/style/some-performance.scrbl

@@ -4,15 +4,15 @@
 
 @; -----------------------------------------------------------------------------
 
-@title{Some Performance Hints}
+@title{Language and Performance}
 
 When you write a module, you first pick a language. In Racket you can
  choose a lot of languages. The most important choice concerns @rkt/base[]
  vs @rkt[].
 
-If you are writing a script, try to use @rkt/base[]. The @rkt/base[]
+If you are writing a script, try using @rkt/base[]. The @rkt/base[]
  language loads significantly faster than the @rkt[] language because it is
- significantly smaller than the @rkt[].
+ much smaller than the @rkt[].
 
 If your module is intended as a library, stick to @rkt/base[]. That way
  script writers can use it without incurring the overhead of loading all of

collects/scribblings/style/style.scrbl

@@ -7,46 +7,49 @@
 
 @; -----------------------------------------------------------------------------
 
-Since 1995 PLT has grown from a handful of people who worked on/with the
+Since 1995 PLT has grown from a handful of ``repository contributors'' to
- repository to three dozen and more. This growth naturally implies a lot
+ three dozen and more. This growth implies a lot of learning on our side
- of learning on our side and the introduction of inconsistencies. It is
+ and the introduction of inconsistencies of programming styles. It is time
- time to leverage the former and to start eliminating the latter. Doing
+ to leverage the former and to start reducing the latter. Doing so will
- so will help us, the developers, and our users, who use the open source
+ help us, the developers, and our users, who use the open source code in
- code in our repository as an implicit guide to Racket programming.
+ our repository as an implicit guide to Racket programming.
 
 To manage the growth of PLT and to showcase good Racket coding, we need
- rules that govern the contributions to the code base. This document
+ rules that govern the contributions to the code base. These rules should
- spells out some basic criteria. They cover a range of topics, from basic
+ achieve some level of consistency across the different portions of the
- work (commit) habits to small syntactic ideas like indentations and
+ code base so that everyone who opens files should easily find his way
- naming. The major goal is to achieve some level of consistency across
+ around.
- the different portions of the code base so that everyone who opens files
- should easily find his way around.
 
-Many pieces of the code base don't live up to our suggestions yet.  Here
+This document spells out the rules. They cover a range of topics, from
- is how we get started. We encourage everyone to look over the commit
+ basic work (commit) habits to small syntactic ideas like indentations and
- messages. If you see problems with the code deltas, let the committer
+ naming.
- know. If you see a bug fix without docs and tests, let the committer
- know. Code should be viewed by more than one person because a second
- person is likely to catch logical mistakes, performance problems, and
- unintended effects.  In the past Eli has done a great job catching
- problems; now everyone is asked to do so.
 
-Also, help us improve the existing files. If you need to edit an imperfect
+Many pieces of the code base don't live up to the rules yet.  Here is how
- file, you will need to spend some time understanding its workings. If
+ we get started. When you start a new file, stick to the rules. If you need
- doing so takes quite a while, please take the time to fix portions of the
+ to edit a file, you will need to spend some time understanding its
- file. After all, if the inconsistencies throw you off for that much time,
+ workings. If doing so takes quite a while due to inconsistencies with the
- others are likely to have the same problems. If you help fixing it, we
+ rules, please take the time to fix (portions of) the file. After all, if
- reduce future maintenance time. In other words, whoever touches the file
+ the inconsistencies throw you off for that much time, others are likely to
- next will be grateful to you.
+ have the same problems. If you help fixing it, you reduce future
+ maintenance time. Whoever touches the file next will be grateful to you.
+ @emph{Do} run the test suites, and do @emph{not} change the behavior of
+ the file.
 
-@bold{Request} This document isn't complete and it isn't perfect. In other
+Also, we encourage everyone to look over the commit messages. If you see
- words, it is also a call for improvements and suggestions.  If you have
+ problems with the code deltas, let the contributor know. If you see a bug
- ideas, contact the first author via email.
+ fix without docs and tests, let the contributor know. Code should be
+ viewed by more than one person because a second person is likely to catch
+ logical mistakes, performance problems, and unintended effects.
 
-@bold{Note} If the style guide doesn't suit your personal style because
+@bold{Request} This document isn't complete and it isn't perfect. Consider
-you grew up on something different, fine. Use your @emph{personal style}
+ it a call for improvements and suggestions.  If you have ideas, contact
-for your @emph{personal programs}, but do use this style guide when you
+ the first author via email. If your request gets ignored, appeal to all
-create code for the PLT code base.
+ four authors.
+
+@bold{Note} If the style guide doesn't suit your personal style because you
+ grew up on something different, fine. Use your @emph{personal style} for
+ your @emph{personal programs}, but do use this style guide when you create
+ code for the PLT code base.
 
 @; -----------------------------------------------------------------------------
 
@@ -55,3 +58,4 @@ create code for the PLT code base.
 @include-section["unit.scrbl"]
 @include-section["constructs.scrbl"]
 @include-section["textual.scrbl"]
+@include-section["branch-and-commit.scrbl"]

collects/scribblings/style/unit.scrbl

@@ -33,35 +33,35 @@ Its interface describes which services it provides, and its body implements
  (require "game-basics.rkt")
 
  (provide
-  ;; Strategy = GameState -> Action
+  ;; Strtgy = GameState -> Action
 
-  ;; Strategy
+  ;; Strtgy
-  ;; a GUI-based plug in for people
+  ;; a person's strategy
   human-strategy
 
-  ;; Strategy
+  ;; Strtgy
   ;; a complete tree traversal
   ai-1-strategy
 
-  ;; Strategy
+  ;; Strtgy
   ;; alpha-beta pruning traversal
   ai-2-strategy)
 
- ;; ------------------------------------------------------------------------------------------
+;; ------------------------------------------------------------------
  (define (general-strategy p)
    ... )
 
- ;; ------------------------------------------------------------------------------------------
+;; ------------------------------------------------------------------
  ... some 100 lines ...
  (define human-strategy
    (general-strategy create-gui))
 
- ;; ------------------------------------------------------------------------------------------
+;; ------------------------------------------------------------------
  ... some 100 lines ...
  (define ai-1-strategy
    (general-strategy traversal))
 
- ;; ------------------------------------------------------------------------------------------
+;; ------------------------------------------------------------------
  ... some 100 lines ...
  (define ai-2-strategy
    (general-strategy alpha-beta))))
@@ -76,26 +76,26 @@ Its interface describes which services it provides, and its body implements
 
  (require "game-basics.rkt")
 
- ;; Strategy = GameState -> Action
+ ;; Strtgy = GameState -> Action
 
- ;; ------------------------------------------------------------------------------------------
+;; ------------------------------------------------------------------
  (define (general-strategy p)
    ... )
  ... some 100 lines ...
 
- ;; ------------------------------------------------------------------------------------------
+;; ------------------------------------------------------------------
  (provide
-  ;; Strategy
+  ;; Strtgy
-  ;; a GUI-based plug in for people
+  ;; a person's strategy
   human-strategy)
 
  (define human-strategy
    (general-strategy create-gui))
  ... some 100 lines ...
 
- ;; ------------------------------------------------------------------------------------------
+;; ------------------------------------------------------------------
  (provide
-  ;; Strategy
+  ;; Strtgy
   ;; a complete tree traversal
   ai-1-strategy)
 
@@ -103,9 +103,9 @@ Its interface describes which services it provides, and its body implements
    (general-strategy traversal))
  ... some 100 lines ...
 
- ;; ------------------------------------------------------------------------------------------
+;; ------------------------------------------------------------------
  (provide
-  ;; Strategy
+  ;; Strtgy
   ;; alpha-beta pruning traversal
   ai-2-strategy)