diff --git a/collects/scribblings/style/branch-and-commit.scrbl b/collects/scribblings/style/branch-and-commit.scrbl index 4e80902504..a9657dc666 100644 --- a/collects/scribblings/style/branch-and-commit.scrbl +++ b/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, diff --git a/collects/scribblings/style/constructs.scrbl b/collects/scribblings/style/constructs.scrbl index 032837d34f..474df9a75a 100644 --- a/collects/scribblings/style/constructs.scrbl +++ b/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 diff --git a/collects/scribblings/style/textual.scrbl b/collects/scribblings/style/textual.scrbl index 81039813cd..18630b245e 100644 --- a/collects/scribblings/style/textual.scrbl +++ b/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} diff --git a/collects/scribblings/style/unit.scrbl b/collects/scribblings/style/unit.scrbl index 86c88cf98d..88fa8b28af 100644 --- a/collects/scribblings/style/unit.scrbl +++ b/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. +