diff --git a/collects/scribblings/style/correct-maintain-speed.scrbl b/collects/scribblings/style/correct-maintain-speed.scrbl index ffaa5ad626..c1d30c59a0 100644 --- a/collects/scribblings/style/correct-maintain-speed.scrbl +++ b/collects/scribblings/style/correct-maintain-speed.scrbl @@ -21,7 +21,7 @@ three points. Specifically, it spells out suggestions @emph{that you can check} and that everyone else can check. @; ----------------------------------------------------------------------------- -@section{Correctness} +@section[#:tag "correctness"]{Correctness} @nested[#:style 'inset]{I have bug reports, therefore I exist. -- Matthias, watching Matthew, Robby, Shriram and others create the original code base} @@ -96,8 +96,9 @@ In order to document code, refer to the and make use of other useful cross-references. Code comprehension also requires adherence to basic elements of style and - some internal documentation. The rest of this document is about these - elements of style, including some suggestions on internal documentation. + some internal documentation. The rest of this document is mostly about + these elements of style, including some suggestions on internal + documentation. @; ----------------------------------------------------------------------------- @section{Speed} @@ -131,4 +132,5 @@ Stress tests don't normally have an expected output, so they never improvement, just document the weakness in the external library and move on. -We are not perfectionist. We produce reasonable software. +We are not perfectionists. We produce reasonable software. + diff --git a/collects/scribblings/style/size.scrbl b/collects/scribblings/style/size.scrbl index 09b8f52aa4..16acef748d 100644 --- a/collects/scribblings/style/size.scrbl +++ b/collects/scribblings/style/size.scrbl @@ -11,4 +11,6 @@ Keep functions small. Keep classes small. Keep units small. Keep modules small. Anytime a unit of code looks incomprehensible, it is probably too large. Break it up into smaller units. To bring across what these smaller -units compute, implement or serve, use meaningful names. +units compute, implement or serve, use meaningful names. Conversely, if you +can't come up with a good name for such units, you are probably looking at +the wrong kind of division; consider alternatives. diff --git a/collects/scribblings/style/some-performance.scrbl b/collects/scribblings/style/some-performance.scrbl new file mode 100644 index 0000000000..dd259b6063 --- /dev/null +++ b/collects/scribblings/style/some-performance.scrbl @@ -0,0 +1,17 @@ +#lang scribble/base + +@(require "shared.rkt") + +@; ----------------------------------------------------------------------------- +@(define rurl "http://docs.racket-lang.org/reference/index.html?q=racket/base") +@(define (rkt) @hyperlink[rurl]{racket}) +@(define (rkt/base) @hyperlink[rurl]{racket/base}) + +@title{Some Performance Hints} + +Use @rkt/base[] instead of @rkt[] for any library that others may use + eventually. For all other modules, use @rkt[]. + +The @rkt/base[] language loads significantly faster than the @rkt[] +language and is also significnatly smaller. Conversely, it is much more +convenient to program with @rkt[] than @rkt/base[]. diff --git a/collects/scribblings/style/style.scrbl b/collects/scribblings/style/style.scrbl index 45f11aeee3..e82c3754d9 100644 --- a/collects/scribblings/style/style.scrbl +++ b/collects/scribblings/style/style.scrbl @@ -3,12 +3,12 @@ @(require "shared.rkt") @title{How to Program Racket} -@author{Matthias Felleisen, Matthew Flatt} +@author{Matthias Felleisen, Matthew Flatt, Robby Findler, Jay McCarthy} @; ----------------------------------------------------------------------------- Since 1995 PLT has grown from a handful of people who worked on/with the - repository to three dozen and more. In addition, Racekt is an open source + repository to three dozen and more. In addition, Racket is an open source project, meaning other people study the code in the repository and use it as an implicit guide to Racket programming. To manage the growth of the PLT developer basis and to showcase good Racket coding, every contribution @@ -33,5 +33,6 @@ This document spells out these criteria, and it is also a call for @; ----------------------------------------------------------------------------- @include-section["correct-maintain-speed.scrbl"] +@include-section["some-performance.scrbl"] @include-section["size.scrbl"] @include-section["textual.scrbl"] diff --git a/collects/scribblings/style/textual.scrbl b/collects/scribblings/style/textual.scrbl index 8d8900f451..c77814fd23 100644 --- a/collects/scribblings/style/textual.scrbl +++ b/collects/scribblings/style/textual.scrbl @@ -11,7 +11,10 @@ Simple textual conventions help eyes find pieces of code quickly. Here are some of those that are easy to check---some automatically and some manually. If you find yourself editing a file that violates some of the -constraints below, edit it into the proper shape. +constraints below, edit it into the proper +shape. @margin-note{@bold{Warning}: On rare occasion a unit test may depend +on the indentation of a file. This is extremely rare but you should be +aware of it.} @; ----------------------------------------------------------------------------- @section{Indentation} @@ -21,7 +24,9 @@ on. So use DrRacket's indentation style. Here is what this means. @nested[#:style 'inset]{ For every file in the repository, DrRacket's "indent all" functions leaves the file alone.} -That's all there is to it. +That's all there is to it. @margin-note{See @secref{correctness}. If you +really believe that DrRacket indents some construct improperly, submit a +bug report. When the bug report is closed, the discussion is finished.} If you prefer to use some other editor (emacs, vi/m, etc), program it so that it follows DrRacket's indentation style.