From 05ae784d1fe03046bfab5d3e6069fc26499b2fc8 Mon Sep 17 00:00:00 2001 From: Matthias Felleisen Date: Mon, 21 Feb 2011 15:00:32 -0500 Subject: [PATCH] [Style] some of Robby's suggestions --- collects/scribblings/style/constructs.scrbl | 10 ++-- .../style/correct-maintain-speed.scrbl | 10 ++-- collects/scribblings/style/shared.rkt | 46 +++++++++++++++++-- .../scribblings/style/some-performance.scrbl | 3 -- collects/scribblings/style/textual.scrbl | 42 +++++++++++++++++ 5 files changed, 98 insertions(+), 13 deletions(-) diff --git a/collects/scribblings/style/constructs.scrbl b/collects/scribblings/style/constructs.scrbl index bf149cc2d7..fe3bd384fe 100644 --- a/collects/scribblings/style/constructs.scrbl +++ b/collects/scribblings/style/constructs.scrbl @@ -42,9 +42,10 @@ racket @; ----------------------------------------------------------------------------- @section{Conditionals} -Like definitional constructs, conditionals come in many flavors, too. Because -@scheme[cond] and its relatives now allow local uses of @scheme[define], you -should prefer them over @scheme[if]. +Like definitional constructs, conditionals come in many flavors, +too. Because @scheme[cond] and its relatives (@scheme[case], +@scheme[match], etc) now allow local uses of @scheme[define], you should +prefer them over @scheme[if]. @compare[ @racketmod[#:file @@ -71,3 +72,6 @@ racket (curved fst (chk rst))))) ] ] + +Of course you should also favor @scheme[cond] (and its relatives) over +@scheme[if] to match the shape of the data definition. diff --git a/collects/scribblings/style/correct-maintain-speed.scrbl b/collects/scribblings/style/correct-maintain-speed.scrbl index 09571f914b..759e0a634c 100644 --- a/collects/scribblings/style/correct-maintain-speed.scrbl +++ b/collects/scribblings/style/correct-maintain-speed.scrbl @@ -123,8 +123,8 @@ Making code fast is an endless task. Making code @emph{reasonably} fast is the goal. It is especially the goal for all pieces of the code base that are reused - elsewhere. Write them using @racketmod[racket] so that they don't affect - the load-time for scripts. See the next section. + 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, exercise your code on some reasonably large inputs. Add a file to the test @@ -156,5 +156,7 @@ And as you read on, keep in mind that we are not perfectionists. We produce 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 - to complex, please push all pieces at once so that the readers can see how - things belong together. + 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. diff --git a/collects/scribblings/style/shared.rkt b/collects/scribblings/style/shared.rkt index 29a2ba8eae..e385c6e7ad 100644 --- a/collects/scribblings/style/shared.rkt +++ b/collects/scribblings/style/shared.rkt @@ -1,8 +1,9 @@ -#lang racket +#lang s-exp racket ; things to be shared among all sections of the style guide (require (for-label racket) + scribble/base scribble/manual scribble/struct (only-in scribble/core table-columns style) @@ -12,10 +13,17 @@ (provide (for-label (all-from-out racket)) (all-from-out scribble/manual)) -(provide compare) +(provide + compare ;; create a comparison box for two code snippets + ;; good ;; label a code fragment 'good' [doesn't work] + ;; bad ;; label a code fragment 'bad' [doesn't work] + rkt rkt/base rkt/gui) -;; compare: two elements, +(define (rkt) (racketmodname racket)) +(define (rkt/base) (racketmodname racket/base)) +(define (rkt/gui) (racketmodname racket/gui)) +;; compare: two code snippets, in two columns: left is good, right is bad (define (compare stuff1 stuff2) (define stuff (list (list stuff1) (list stuff2))) (define space (style #f (list (attributes '((width . "500") (valign . "top")))))) @@ -25,3 +33,35 @@ (attributes '((border . "1") (cellpadding . "10"))) (table-columns (make-list (length stuff) space)))) (apply map (compose make-flow list) stuff))) + +;; =================================================================================================== +;; the following doesn't work + +;; label a piece of syntax good or bad +(define-syntax-rule + (good form code ...) +(racketmod #:file +(tt "good") +racket +form +code +...)) + +(define-syntax-rule + (bad form code ...) + (labeled-code + "bad" + form + code + ...)) + +(define-syntax-rule + (labeled-code lbl:string form code ...) + ;; ===> + (racketmod + #:file + (tt lbl:string) + racket + form + code + ...)) \ No newline at end of file diff --git a/collects/scribblings/style/some-performance.scrbl b/collects/scribblings/style/some-performance.scrbl index 616fa64150..0c47e9350a 100644 --- a/collects/scribblings/style/some-performance.scrbl +++ b/collects/scribblings/style/some-performance.scrbl @@ -3,9 +3,6 @@ @(require "shared.rkt") @; ----------------------------------------------------------------------------- -@(define (rkt) @racketmodname[racket]) -@(define (rkt/base) @racketmodname[racket/base]) -@(define (rkt/gui) @racketmodname[racket/gui]) @title{Some Performance Hints} diff --git a/collects/scribblings/style/textual.scrbl b/collects/scribblings/style/textual.scrbl index 5948624765..ff80d08a66 100644 --- a/collects/scribblings/style/textual.scrbl +++ b/collects/scribblings/style/textual.scrbl @@ -103,6 +103,48 @@ racket ...) ] ] + +All of the arguments to a function belong on a single line unless the line +becomes too long, in which case you want to put each argument expression on +its own line + +@compare[ +@racketmod[#:file +@tt{good} +racket + +(place-image img 10 10 background) + +(code:comment #, @t{and}) + +(composition img + (- width hdelta) + (- height vdelta) + bg) + +] + +@racketmod[#:file +@tt{bad} +racket + +(composition ufo-with-flames + 10 v-delta bg) + +]] + +Here is an exception: +@racketmod[#:file +@tt{good} +racket + +(overlay/offset (rectangle 100 10 "solid" "blue") + 10 10 + (rectangle 10 100 "solid" "red")) +] + In this case, the two arguments on line 2 are both short and conceptually + related. + @margin-note{We need more of these rules} @; -----------------------------------------------------------------------------