diff --git a/collects/scribblings/style/correct-maintain-speed.scrbl b/collects/scribblings/style/correct-maintain-speed.scrbl index b09db79084..a2aa03521b 100644 --- a/collects/scribblings/style/correct-maintain-speed.scrbl +++ b/collects/scribblings/style/correct-maintain-speed.scrbl @@ -13,7 +13,6 @@ Code is maintainable. Code is fast. -The following suggestions are about creating maintainable and fast -code. The production of correct code is a project for life, and depends to -a high degree on reflection---i.e., thinking about what you are doing and -not just doing it. +This guide is about creating maintainable code and it touches on +correctness and speed on occasion. For the former, formulate test suites; +for the latter, start with stress test suites. diff --git a/collects/scribblings/style/size.scrbl b/collects/scribblings/style/size.scrbl new file mode 100644 index 0000000000..09b8f52aa4 --- /dev/null +++ b/collects/scribblings/style/size.scrbl @@ -0,0 +1,14 @@ +#lang scribble/base + +@(require "shared.rkt") + +@title{Size Matters} + +@; ----------------------------------------------------------------------------- +@section{Code Units} + +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. diff --git a/collects/scribblings/style/style.scrbl b/collects/scribblings/style/style.scrbl index f69fdd394a..45f11aeee3 100644 --- a/collects/scribblings/style/style.scrbl +++ b/collects/scribblings/style/style.scrbl @@ -22,7 +22,16 @@ This document spells out these criteria, and it is also a call for meta-code, and the same ideas apply. If you have suggestions, contact the authors via email. +@bold{Note} We understand that some of the files in the code base do not + live up to these standards. Help us improve these files. If you need to + edit and understand a file that fails in some ways, take the time to + reorganize it properly as soon as the comprehension step takes longer than + a few minutes. Because if understanding takes a lot of time, it is likely + that the file isn't maintainable. Whoever touches the file next will be + grateful. + @; ----------------------------------------------------------------------------- @include-section["correct-maintain-speed.scrbl"] +@include-section["size.scrbl"] @include-section["textual.scrbl"]