diff --git a/collects/scribblings/style/correct-maintain-speed.scrbl b/collects/scribblings/style/correct-maintain-speed.scrbl index 9fa43d19d0..09571f914b 100644 --- a/collects/scribblings/style/correct-maintain-speed.scrbl +++ b/collects/scribblings/style/correct-maintain-speed.scrbl @@ -12,6 +12,13 @@ adjectives is critical: correct is more important than maintainable; maintainable is more important than fast; and fast is important to include, because nobody wants to live with slow programs. +@margin-note{This ordering is occasionally wrong. For example, we could + avoid IEEE floating point numbers nearly all of the time. To make this + precise, the @scheme[sqrt] function could return a rational number whose + value was the same as the IEEE float result. We don't do such silly + things, however, because we have decided to value speed over precision in + this context.} + Code is correct. Code is maintainable. @@ -97,10 +104,16 @@ In order to document code, refer to the @tt{for-label} @tt{require}s 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 mostly about - these elements of style, including some suggestions on internal - documentation. +Without adherence to basic elements of style and some internal + documentation, code comprehension becomes impossible. The rest of this + document is mostly about these elements of style, including some + suggestions on internal documentation. + +Having said that, the production of a system like Racket occasionally + requires experimentation and experimental code. Once we understand this + new pieces of functionality, though, it is imperative to return and + improve maintainability and work on correctness. You may even consider + converting to Typed Racket eventually. @; ----------------------------------------------------------------------------- @section{Speed} @@ -138,6 +151,10 @@ Stress tests don't normally have an expected output, so they never And as you read on, keep in mind that we are not perfectionists. We produce reasonable software. -@nested[#:style 'inset]{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.} +@section{Commit} + +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. diff --git a/collects/scribblings/style/style.scrbl b/collects/scribblings/style/style.scrbl index 11a83f2b2e..cd01b02541 100644 --- a/collects/scribblings/style/style.scrbl +++ b/collects/scribblings/style/style.scrbl @@ -31,13 +31,13 @@ Many pieces of the code base don't live up to our suggestions yet. Here unintended effects. In the past Eli has done a great job catching problems; now everyone is asked to do so. -Also, help us improve the existing files. If you need to edit and - understand an imperfect file, take the time to fix some of it as soon as - comprehending the file takes longer than a few minutes. After all, if - the inconsistencies throw you off for that much time, others are likely - to have the same problems. If you help fixing it, we reduce future - maintenance time. In other words, whoever touches the file next will be - grateful to you. +Also, help us improve the existing files. If you need to edit an imperfect + file, you will need to spend some time understanding its workings. If + doing so takes quite a while, please take the time to fix portions of the + file. After all, if the inconsistencies throw you off for that much time, + others are likely to have the same problems. If you help fixing it, we + reduce future maintenance time. In other words, whoever touches the file + next will be grateful to you. @bold{Request} This document isn't complete and it isn't perfect. In other words, it is also a call for improvements and suggestions. If you have