1Basic Facts of Life

This ordering is occasionally wrong. For example, we could
avoid IEEE floating point numbers nearly all of the time. To make this
precise, the Racket sqrt function could return a rational number
close to the IEEE float result. We don’t do such silly things, however,
because we have decided to value speed over precision in this context.
Strive to write code that is correct; maintainable; and fast. The ordering
of these 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.

This section explains these three points as far as the Racket code base is
concerned. The rest of this guide is to spell out suggestions that should
help you make correct, maintainable, and fast contributions to the Racket
code base.

1.1Correctness and Testing

I have bug reports, therefore I exist. – Matthias,
watching Matthew, Robby, Shriram and others create the original code base

It is the way we choose to fight our bugs that
determines our character, not their presence or absence. – Robby, in response

PLT aims to release good code and to eliminate mistakes as quickly as
possible. All software has mistakes; complete correctness is a
perfectionist goal. If mistakes are unknown, the software isn’t being
used. The goal is, however, to ensure some basic level of correctness
before a feature is released and to ensure that the same mistake isn’t
introduced again.

We ensure this basic level of correctness with large test suites. Our test
suites contain tests at all levels. In addition to unit tests, you will
find test suites that use a “random testing” strategy and tools, others
use fuzz testing, yet others are end-to-end “systems level” tests, and
DrRacket comes with an automatic GUI player that explores its
functionality.

For details on testing in the context of the Racket code base, see
Testing.

1.2Maintenance

If we wish to create maintainable code, we must ensure that our code is
comprehensible. Code is comprehensible when you can understand its
external purpose; when you can guess from its external purpose at its
organization; when the organization and the code live up to consistent
criteria of style; and when the occasional complex part comes with
internal documentation.

Released code must have documentation. Conversely a change to the external
behavior of code must induce a simultaneous change to its documentation.
Here “simultaneous” means that the two changes are in the same ’push’
to the code base, not necessarily in the same ’commit’. Also see
Retiquette: Branch and Commit for more on Git actions.

For style rules on documenting code, refer to the
style
guide in the Scribble manual. Ideally documentation comes in two parts,
possibly located in the same document: a “Guide” section, which explains
the purpose and suggests use cases, and a traditional “Reference”
section, which presents the minutiae. The documentation for HtDP/2e
teachpacks is an example where the two parts are collocated. Also consider
adding examples for each function and construct in your “Reference”
section. Finally, ensure you have all the correct for-labelrequires and make use of other useful cross-references.

Having said that, the production of a system like Racket occasionally
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
Racket eventually.

Without adherence to basic elements of style, code comprehension becomes
impossible. The rest of this document is mostly about these elements of
style, including some suggestions on minimal internal documentation.

1.3Speed

Making code fast is an endless task. Making code reasonably fast is the goal.

As with correctness, performance demands some “testing.” At a minimum,
exercise your code on some reasonably realistic inputs and some larger
ones. Add a file to the test suite that runs large inputs regularly. For
example, a regular test suite for a Universe display deals with a 50 x 50
display window; one of its stress tests checks whether Universe event
handlers and drawing routines can cope with laptop size displays or even a
30in display. Or, if you were to write a library for a queue data
structure, a regular test suite ensures that it deals correctly with
enqueue and dequeue for small queues, including empty ones; a stress test
suite for the same library would run the queue operations on a variety of
queue sizes, including very large queues of say tens of thousands
elements.

Stress tests don’t normally have an expected output, so they never
pass. The practice of writing stress tests exposes implementation flaws or
provides comparative data to be used when choosing between two APIs. Just
writing them and keeping them around reminds us that things can go bad and
we can detect when performance degrades through some other door. Most
importantly, a stress test may reveal that your code isn’t implementing an
algorithm with the expected O(.) running time. Finding out that
much alone is useful. If you can’t think of an improvement, just document
the weakness in the external library and move on.

And as you read on, keep in mind that we are not perfectionists. We produce
reasonable software.