[Style] Casey's message, boxes around all labeled code snippets

This commit is contained in:
Matthias Felleisen 2011-08-11 18:33:24 -04:00 committed by Eli Barzilay
parent 3b1e96c0c0
commit 49f4cb6072
7 changed files with 63 additions and 53 deletions

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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))

View File

@ -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 "" <file> ...}}
@tt{failure} tests, you may wish to disable DrDr's checking like this:
@verbatim[#:indent 2]{
git prop set drdr:command-line "" <file> ...
}
This is a Racket-specific @tt{git} command.
@; -----------------------------------------------------------------------------

View File

@ -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}

View File

@ -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