From 49f4cb607234cf8470475ae2b2b82af7d02c4468 Mon Sep 17 00:00:00 2001 From: Matthias Felleisen Date: Thu, 11 Aug 2011 18:33:24 -0400 Subject: [PATCH] [Style] Casey's message, boxes around all labeled code snippets --- .../scribblings/style/branch-and-commit.scrbl | 6 +-- collects/scribblings/style/constructs.scrbl | 34 +++++++------ .../style/correct-maintain-speed.scrbl | 2 +- collects/scribblings/style/shared.rkt | 6 +++ collects/scribblings/style/testing.scrbl | 10 ++-- collects/scribblings/style/textual.scrbl | 48 ++++++++++--------- collects/scribblings/style/unit.scrbl | 10 ++-- 7 files changed, 63 insertions(+), 53 deletions(-) diff --git a/collects/scribblings/style/branch-and-commit.scrbl b/collects/scribblings/style/branch-and-commit.scrbl index d3634cd9d6..cd5488ee15 100644 --- a/collects/scribblings/style/branch-and-commit.scrbl +++ b/collects/scribblings/style/branch-and-commit.scrbl @@ -5,8 +5,8 @@ @title[#:tag "branch-and-commit"]{Branch and Commit} Working with the code base also requires style rules for actions on the -repository. Currently we are using Git and below are a few rules on how to -act in this context. + repository. Currently we are using Git and below are a few rules on how to + act in this context. @; ----------------------------------------------------------------------------- @section{Commit} @@ -27,7 +27,7 @@ act in this context. @bold{Style change commit:} Submit changes to the style of a file separately from changes to its behavior (new features, bugs). -Write meaningful commit messages. The first line (say 80 chars) should +Write meaningful commit messages. The first line (say 72 chars) should provide a concise summary of the commit. If the message must be longer, edit the rest of the message in your text editor and leave a blank line between the summary line and the rest of the message. The message for bug diff --git a/collects/scribblings/style/constructs.scrbl b/collects/scribblings/style/constructs.scrbl index f4c4574711..e0a82992a9 100644 --- a/collects/scribblings/style/constructs.scrbl +++ b/collects/scribblings/style/constructs.scrbl @@ -78,24 +78,22 @@ racket @tt{good} racket -(define-syntax (increment! stx) +(define-syntax (bump stx) (syntax-case stx () [(_ s sn fn i) - (with-syntax ([w (r #'s)]) - (define g (ff #'sn #'w)) - ...)])) + (define g (ff #'sn)) + #'( ....)])) ] @; ----------------------------------------------------------------------------- @racketmod[#:file @tt{bad} racket -(define-syntax (increment! stx) +(define-syntax (bump stx) (syntax-case stx () [(_ s sn fn i) - (with-syntax ([w (r #'s)]) - (let ([g (ff #'sn #'w)]) - ...))])) + (let ([g (ff #'sn)]) + #'( ....))])) ] ] @@ -118,8 +116,8 @@ racket (define f (fir l)) (define r (rest l)) (if (discounted? f) - (discount-rate f) - (curved f (chk r)))]) + (rate f) + (curved (g r)))]) ] @racketmod[#:file @tt{bad} @@ -130,8 +128,8 @@ racket (let ([f (fir l)] [r (rest l)]) (if (discounted? f) - (discount-rate f) - (curved f (chk r))))) + (rate f) + (curved (g r))))) ] ] @@ -159,10 +157,9 @@ racket (define (next-month date) (define day (first date)) (define month (second date)) - (define year (third date)) (if (= month 12) - `(,(+ day 1) 1 ,year) - `(,day ,(+ month 1) ,year))) + `(,(+ day 1) 1) + `(,day ,(+ month 1)))) ] @; ----------------------------------------------------------------------------- @racketmod[#:file @@ -170,10 +167,11 @@ racket racket (define (next-month d) (if (= (cadr d) 12) - `(,(+ (car d) 1) 1 ,(caddr d)) + `(,(+ (car d) 1) + 1 + ,(caddr d)) `(,(car d) - ,(+ (cadr d) 1) - ,(caddr d)))) + ,(+ (cadr d) 1)))) ] ] Clearly ``too deeply'' is subjective. On occasion it also isn't the diff --git a/collects/scribblings/style/correct-maintain-speed.scrbl b/collects/scribblings/style/correct-maintain-speed.scrbl index 930aa619f3..7148b08358 100644 --- a/collects/scribblings/style/correct-maintain-speed.scrbl +++ b/collects/scribblings/style/correct-maintain-speed.scrbl @@ -76,7 +76,7 @@ For style rules on documenting code, refer to the @tt{require}s and make use of other useful cross-references. Having said that, the production of a system like Racket occasionally - requires experimentation. Once we understand this new pieces of + requires experimentation. Once we understand these new pieces of functionality, though, it is imperative to discard the ``failure branches'' of an experiment and to turn the successful part into a maintainable package. You may even consider converting your code to Typed diff --git a/collects/scribblings/style/shared.rkt b/collects/scribblings/style/shared.rkt index 0de68749cd..2cde471299 100644 --- a/collects/scribblings/style/shared.rkt +++ b/collects/scribblings/style/shared.rkt @@ -1,5 +1,6 @@ #lang s-exp racket +;; --------------------------------------------------------------------------------------------------- ; things to be shared among all sections of the style guide (require (for-label racket) @@ -14,6 +15,7 @@ (all-from-out scribble/manual)) (provide + LINEWIDTH codebox compare ;; create a comparison box for two code snippets ;; good ;; label a code fragment 'good' [doesn't work] @@ -22,6 +24,10 @@ row-table rkt rkt/base rkt/gui) +(define (LINEWIDTH) "102") + +;; --------------------------------------------------------------------------------------------------- + (define (rkt) (racketmodname racket)) (define (rkt/base) (racketmodname racket/base)) (define (rkt/gui) (racketmodname racket/gui)) diff --git a/collects/scribblings/style/testing.scrbl b/collects/scribblings/style/testing.scrbl index 7c51024046..e40cd24c5f 100644 --- a/collects/scribblings/style/testing.scrbl +++ b/collects/scribblings/style/testing.scrbl @@ -17,8 +17,8 @@ Run the test suites before you commit. To facilitate testing, we urge you to add a @tt{TESTME.txt} file to your collections. Ideally, you may also wish to have a file in this directory that runs the basic tests. See the @hyperlink["https://github.com/plt/racket/tree/master/collects/2htdp/"]{2htdp}, - which is one of the collections with own testing style. The file should - describe where the tests are located, how to run thee tests, and what to + which is one of the collections with its own testing style. The file should + describe where the tests are located, how to run these tests, and what to look for in terms of successes and failures. These files are necessary because different collections have different needs for testing, and testing evolved in many different ways in our history. @@ -32,8 +32,10 @@ After you commit, watch for and read(!) fail. See the @hyperlink["https://github.com/plt/racket/tree/master/collects/tests/typed-scheme"]{Typed Racket testing arrangement} for an example. When you create such - @tt{failure} tests, you may to disable DrDr's checking like this: -@nested{@tt{git prop set drdr:command-line "" ...}} + @tt{failure} tests, you may wish to disable DrDr's checking like this: +@verbatim[#:indent 2]{ + git prop set drdr:command-line "" ... +} This is a Racket-specific @tt{git} command. @; ----------------------------------------------------------------------------- diff --git a/collects/scribblings/style/textual.scrbl b/collects/scribblings/style/textual.scrbl index 5557d5b3f6..78985642a1 100644 --- a/collects/scribblings/style/textual.scrbl +++ b/collects/scribblings/style/textual.scrbl @@ -131,6 +131,28 @@ Do not use tab characters in your code. Tabs make it hard to use textual @item{in vi: set expandtab.} ] +@; ----------------------------------------------------------------------------- +@section{Line Width} + +A line in a Racket file is at most @LINEWIDTH[] characters wide. + +If you prefer a narrower width than @LINEWIDTH[], and if you stick to this +width ``religiously,'' add a note to the top of the file---right below the +purpose statement---that nobody should violate your file-local rule. + +This number is a compromise. People used to recommend a line width of 80 or +72 column. The number is a historical artifact. It is also a good number +for several different reasons: printing code in text mode, displaying code +at reasonable font sizes, comparing several different pieces of code on a +monitor, and possibly more. So age doesn't make it incorrect. We regularly +read code on monitors that accommodate close to 250 columns, and on +occasion, our monitors are even wider. It is time to allow for somewhat +more width in exchange for meaningful identifiers. + +So, when you create a file, add a line with ";; " followed by ctrl-U 99 and +"-". When you separate "sections" of code in a file, insert the same line. +These lines help both writers and readers to orient themselves in a file. + @; ----------------------------------------------------------------------------- @section{Line Breaks} @@ -158,14 +180,15 @@ racket ] It is acceptable to have an entire @racket[if] expressions on one line if -it fits within the specified line width: +it fits within the specified line width (@LINEWIDTH[]): +@codebox[ @racketmod[#:file @tt{also good} racket (if (positive? x) x (- x)) ] - +] Each definition and each local definition deserves at least one line. @@ -231,27 +254,6 @@ racket In this case, the two arguments on line 2 are both conceptually related and short. -@; ----------------------------------------------------------------------------- -@section{Line Width} - -A line in a Racket file is at most 102 characters wide. - -If you prefer a narrower width than 102, and if you stick to this width -``religiously,'' add a note to the top of the file---right below the -purpose statement---that nobody should violate your file-local rule. - -This number is a compromise. People used to recommend a line width of 80 or -72 column. The number is a historical artifact. It is also a good number -for several different reasons: printing code in text mode, displaying code -at reasonable font sizes, comparing several different pieces of code on a -monitor, and possibly more. So age doesn't make it incorrect. We regularly -read code on monitors that accommodate close to 250 columns, and on -occasion, our monitors are even wider. It is time to allow for somewhat -more width in exchange for meaningful identifiers. - -So, when you create a file, add a line with ";; " followed by ctrl-U 99 and -"-". When you separate "sections" of code in a file, insert the same line. -These lines help both writers and readers to orient themselves in a file. @; ----------------------------------------------------------------------------- @section[#:tag "names"]{Names} diff --git a/collects/scribblings/style/unit.scrbl b/collects/scribblings/style/unit.scrbl index 012d8a9923..ca2e59a4e6 100644 --- a/collects/scribblings/style/unit.scrbl +++ b/collects/scribblings/style/unit.scrbl @@ -1,6 +1,6 @@ #lang scribble/base -@(require "shared.rkt") +@(require "shared.rkt" (for-label rackunit)) @title{Units of Code} @@ -34,7 +34,7 @@ A module of 10,000 lines of code is too large. A module of 1,000 lines is 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 roughly 66 lines is usually +And a function/method/syntax-case of roughly 66 lines is usually acceptable. The 66 is based on the length of a 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. Nesting levels and @@ -67,6 +67,7 @@ In order to understand a module's services, organize the module in three sections below the purpose statement: its imports, its exports, and its implementation: @;% +@codebox[ @(begin #reader scribble/comment-reader (racketmod #:file @@ -88,13 +89,14 @@ implementation: (define (tv-client) (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: @;% +@codebox[ @(begin #reader scribble/comment-reader (racketmod #:file @@ -131,7 +133,7 @@ If you choose to use @racket[provide/contract], define auxiliary concepts (define board% (class ... some 900 lines ...)) -)) +))] @;% Avoid @racket[(provide (all-defined-out))] except for general-purpose