[Style] comments from PLT

collects/scribblings/style/textual.scrbl

@@ -13,8 +13,8 @@ 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. @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.}
+on the indentation of a file. This is extremely rare and must be noted at
+the top so that readers do not accidentally re-indent the file.}
 
 @; -----------------------------------------------------------------------------
 @section{Where to Put Parentheses}
@@ -70,6 +70,8 @@ end of long sequences, be those definitions or pieces of data.
      ))
  }]
 ]
+ Doing so is most useful when you expect to add, delete, or swap items in
+ such sequences.
 
 @; -----------------------------------------------------------------------------
 @section{Indentation}
@@ -79,7 +81,7 @@ 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 is all there is to it.
 
 If you prefer to use some other editor (emacs, vi/m, etc), program it so
 that it follows DrRacket's indentation style.
@@ -112,7 +114,10 @@ Examples:
 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.
+indentation functionality. If you add entire languages, say something on
+the order of Typed Racket, we will need to wait for Matthew and Robby to
+provide an indentation protocol on the @verbatim{#lang} line; please be
+patient and use the existing indentation tool anyway.
 
 @; -----------------------------------------------------------------------------
 @section{Line Breaks}
@@ -259,27 +264,51 @@ trvrs-frst
 ])
 ]
 @;
-If you cannot give a unit a good name, consider the possibility that it
-isn't a proper unit of code.
 
-You may use dots between parts of names, e.g., @racket[p.x] to suggest that
-field @racket[x] is selected from struct @racket[p].
+Another widely used convention is to @emph{prefix} a function name with the data
+ type of the main argument. This convention generalizes the selector-style
+ naming scheme of @racket[struct].
+@(begin
+#reader scribble/comment-reader
+[racketmod #:file
+@tt{good}
+racket
 
-In addition to regular alphanumeric characters, Racketeers use a few
-special characters by convention, and these characters indicate something
-about the name:
+board-free-spaces      board-attackable-spaces    board-serialize
+])
+ In contrast, variables use a @emph{suffix} that indicates their type:
+@(begin
+#reader scribble/comment-reader
+[racketmod #:file
+@tt{good}
+racket
+
+(define (win-or-lose? game-state)
+  (define position-nat-nat (game-state-position game-state))
+  (define health-level-nat (game-state-health game-state))
+  (define name-string      (game-state-name game-state))
+  (define name-symbol      (string->symbol name-string))
+  ...)
+])
+ The convention is particularly helpful when the same piece of data shows
+ up in different guises, say, symbols and strings.
+
+Names are bad if they heavily depend on knowledge about the context of the
+ code. It prevents readers from understanding a piece of functionality at
+ an approximate level without also reading large chunks of the surrounding
+ and code.
+
+Finally, in addition to regular alphanumeric characters, Racketeers use a
+ few special characters by convention, and these characters indicate
+ something about the name:
 
 @;column-table[ @col[? ! "@" ^ %] @col[1 2 3 4 5] @col[1 2 3 4 5] ]
 
 @row-table[
  @row[symbol kind example]
- @row[? predicates boolean?]
- @row[! setters    set!]
- @row[% classes    a%]
- @row["@" units      a@]
- @row[^ signatures a^]
+ @row[? "predicates and boolean-valued functions" boolean?]
+ @row[! "setters and field mutators"              set!]
+ @row[% "classes"                                 game-state%]
+ @row[^ "unit signatures"                         game-context^]
+ @row["@" units                                   testing-context@]
 ]
-
-Some Racketeers use the suffix of the name to suggest type(-like)
-information, e.g., @racket[body-xexpr] or @racket[body-xml]. For such uses,
-a colon is commonly found, e.g., @racket[p:posn] or @racket[p:pair-of-numbers].

collects/scribblings/style/unit.scrbl

@@ -4,6 +4,25 @@
 
 @title{Units of Code}
 
+@; -----------------------------------------------------------------------------
+@section{Organization Matters}
+
+We often develop units of code in a bottom-up fashion with some top-down
+planning. There is nothing surprising about this strategy because we build
+code atop of existing libraries, which takes some experimentation, which in
+turn is done in the REPL. We also want testable code quickly, meaning we
+tend to write down those pieces of code first for which we can develop and
+run tests. Readers don't wish to follow our development, however; they wish
+to understand what the code computes without necessarily understanding all
+the details.
+
+So, please take the time to present each unit of code in a top-down
+manner. This starts with the implementation part of a module. Put the
+important functions close to the top, right below any code and comments as
+to what kind of data you use. The rule also applies to classes, where you
+want to expose @racket[public] methods before you tackle @racket[private]
+methods. And the rule applies to units, too.
+
 @; -----------------------------------------------------------------------------
 @section{Size Matters}
 
@@ -239,13 +258,15 @@ Consider using @scheme[provide/contract] for module interfaces.
 
 @subsection{Uniformity of Interface}
 
-Pick a consistency rule for the names of your functions, classes, and
+Pick a consistency rule for naming your functions, classes, and
  methods. Stick to it. For example, you may wish to prefix all exported
-names with the same word, say @racket[syntax-local].
+ names with the name of the data type that they deal with, say
+ @racket[syntax-local].
 
-Pick a consistency rule the parameters of your functions and methods. Stick
-to it. For example, if your module implements an abstract data type (ADT),
-all functions on the ADT should consume the ADT-argument first or last.
+Pick a consistency rule for naming and ordering the parameters of your
+ functions and methods. Stick to it. For example, if your module implements
+ an abstract data type (ADT), all functions on the ADT should consume the
+ ADT-argument first or last.
 
 @subsection{Sections}