[Style] Casey's message, boxes around all labeled code snippets
This commit is contained in:
parent
3b1e96c0c0
commit
49f4cb6072
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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))
|
||||
|
|
|
@ -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.
|
||||
|
||||
@; -----------------------------------------------------------------------------
|
||||
|
|
|
@ -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}
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue
Block a user