[Style] feedback edits

collects/scribblings/style/branch-and-commit.scrbl

@@ -19,7 +19,7 @@ So what is the major lesson of this section? When you fix a bug, make sure
 On occasion, you will find that you are spending a significant amount of
  time working with someone else's code. To avoid potentially painful
  merges, please (1) inform the author when you create the branch and (2)
- set the mail hook @margin-note*{See Eli's write-up on using git in PLT for
+ set the mail hook @margin-note*{See @hyperlink["http://tmp.barzilay.org/git.txt"]{Eli's write-up} on using git in PLT for
  information on the mechanics.} so that git sends a commit message to both
  you and the original author. Furthermore, you should test your changes on
  the actual code base. In some cases it is acceptable to delay such tests,

collects/scribblings/style/constructs.scrbl

@@ -131,7 +131,7 @@ racket
 @section{Structs vs Lists}
 
 Use @racket[struct]s when you represent a combination of a fixed number of
-values.  Don't use lists.
+values.  Or, don't use lists when structures will do.
 
 @; -----------------------------------------------------------------------------
 @section{Lambda vs Define}
@@ -164,6 +164,11 @@ racket
 ]
 
 
+@; -----------------------------------------------------------------------------
+@section{Identity Functions}
+
+The identity function is @racket[values]. Try it with @racket[(values 1 2 3)].
+
 @; -----------------------------------------------------------------------------
 @section{List Traversals}
 
@@ -204,8 +209,7 @@ racket
 
 ;; [Listof X] -> Number
 (define (sum-up s)
-  (for/fold ((sum 0)) ((x s))
-    (+ sum x)))
+  (foldr (lambda (x sum) (+ sum x)) 0 s))
 
 ;; example:
 (sum-up '(1 2 3))
@@ -219,7 +223,8 @@ racket
 @; -----------------------------------------------------------------------------
 @section{Functions vs Macros}
 
-Use functions when possible; do not introduce macros.
+Use functions when possible, Or, do not introduce macros when functions
+will do.
 
 @compare[
 @racketmod[#:file

collects/scribblings/style/textual.scrbl

@@ -91,6 +91,7 @@ Examples:
                     @tt{good}
                     racket
 
+		    (code:comment #, @t{drracket style})
                     (if (positive? (rocket-x r))
                         (launch r)
                         (redirect (- x)))
@@ -100,12 +101,19 @@ Examples:
                      @tt{bad}
                      racket
 
+		     (code:comment #, @t{.el emacs-file if})
                      (if (positive? (rocket-x r))
-                       (launch r)
+                         (launch r)
                        (redirect (- x)))
  ]
 ]
 
+@bold{Caveat}: Until language specifications come with fixed indentation
+rules, we need to use the @emph{default} settings of DrRacket's indentation
+for this rule to make sense. If you add new constructs, say a for loop,
+please contact Robby for advice on how to add a default setting for the
+indentation functionality.
+
 @; -----------------------------------------------------------------------------
 @section{Line Breaks}
 

collects/scribblings/style/unit.scrbl

@@ -12,13 +12,20 @@ Keep units of code small. Keep modules, classes, functions and methods small.
 A module of 10,000 lines of code is too large. A module of 1,000 lines is
  tolerable. A module of 500 lines of code has the right size.
 
-One module should usually a class and its auxiliary functions, which in
+One module should usually contain a class and its auxiliary functions, which in
  turn determines the length of a good-sized class.
 
-And a function (method) of more than 66 lines is barely acceptable. For
- many years we had a limited syntax transformation language that forced
- people to create @emph{huge} functions. This is no longer the case, so
- consider this rule universal.
+And a function (method) of more than 66 lines is usually acceptable. The 66
+is based on the length of a laptop screen with small font. It really means
+"a screen length."
+
+Yes, there are exceptions where functions are more than 1,000 lines long
+ and extremely readable. (The worst part is that I have found 30-line
+ unreadable functions, too.)
+
+For many years we had a limited syntax transformation language that forced
+ people to create @emph{huge} functions. This is no longer the case, so we
+ should try to stick to the rule whenever possible.
 
 If a unit of code looks incomprehensible, it is probably too large. Break
  it up. To bring across what the pieces compute, implement or serve, use
@@ -60,11 +67,50 @@ implementation:
   (big-bang ...))
 ))
 @;%
- If you choose to use @racket[provide/contract], define auxiliary concepts
-  related to the contracts between the @racket[require] and the
-  @racket[provide] sections. A test suite section---if located within the
-  module---should come at the every end, including its specific
-  dependencies, i.e., @racket[require] specifications.
+
+If you choose to use @racket[provide/contract], define auxiliary concepts
+ related to the contracts between the @racket[require] and the
+ @racket[provide] sections:
+@;%
+@(begin
+#reader scribble/comment-reader
+ (racketmod #:file
+ @tt{good}
+ racket/base
+
+;; the module implements a tv server
+
+(require 2htdp/universe htdp/image)
+
+(define player# 3)
+(define plain-board/c
+  (instanceof/c (and/c admin-board%/c board%-contracts/c)))
+
+(define placement/c
+  (flat-named-contract "placement" ...))
+
+(provide/contract
+  [board-init        (-> player#/c plain-board/c)]
+  [create-board      (-> player#/c (listof placement/c)
+                         (or/c plain-board/c string?))]
+  [board-deserialize (-> any/c plain-board/c)])
+
+; implementation:
+(define (board-init n)
+  (new board% ...))
+
+(define (create-board n lop)
+  (define board (board-init n))
+  ...)
+
+(define board%
+  (class ... some 900 lines ...))
+))
+@;%
+
+A test suite section---if located within the module---should come at the
+ every end, including its specific dependencies, i.e., @racket[require]
+ specifications.
 
 @; -----------------------------------------------------------------------------
 @subsection{Require}
@@ -220,6 +266,9 @@ With @racketmodname[rackunit], test suites can be defined within the
 @; -----------------------------------------------------------------------------
 @section{Functions & Methods}
 
-
 If your function or method consumers more than two parameters, consider
 keyword arguments so that call sites can easily be understood.
+
+Please write a purpose statement for your function.
+If you can, add an informal type and/or contract statement.
+