diff options
Diffstat (limited to 'cpp/000organization')
| -rw-r--r-- | cpp/000organization | 173 |
1 files changed, 88 insertions, 85 deletions
diff --git a/cpp/000organization b/cpp/000organization index ab1cee79..6c513809 100644 --- a/cpp/000organization +++ b/cpp/000organization @@ -1,86 +1,89 @@ -// You guessed right: the '000' prefix means you should start reading here. -// -// This project is setup to load all files with a numeric prefix. Just create -// a new file and start hacking. -// -// The first few files (00*) are independent of what this program does, an -// experimental skeleton that will hopefully make it both easier for others to -// understand and more malleable, easier to rewrite and remould into radically -// different shapes without breaking in subtle corner cases. The premise is -// that understandability and rewrite-friendliness are related in a virtuous -// cycle. Doing one well makes it easier to do the other. -// -// Lower down, this file contains a legal, bare-bones C++ program. It doesn't -// do anything yet; subsequent files will add behaviors by inserting lines -// into it with directives like: -// :(after "more events") -// This will insert the following lines after a line in the program containing -// the words "more events". -// -// Directives free up the programmer to order code for others to read rather -// than as forced by the computer or compiler. Each individual feature can be -// organized in a self-contained 'layer' that adds code to many different data -// structures and functions all over the program. The right decomposition into -// layers will let each layer make sense in isolation. -// -// "If I look at any small part of it, I can see what is going on -- I don't -// need to refer to other parts to understand what something is doing. -// -// If I look at any large part in overview, I can see what is going on -- I -// don't need to know all the details to get it. -// -// Every level of detail is as locally coherent and as well thought-out as -// any other level." -// -// -- Richard Gabriel, "The Quality Without A Name" -// (http://dreamsongs.com/Files/PatternsOfSoftware.pdf, page 42) -// -// Directives are powerful; they permit inserting or modifying any point in -// the program. Using them tastefully requires mapping out specific lines as -// waypoints for future layers to hook into. Often such waypoints will be in -// comments, capitalized to hint that other layers rely on their presence. -// -// A single waypoint might have many different code fragments hooking into -// it from all over the codebase. Use 'before' directives to insert -// code at a location in order, top to bottom, and 'after' directives to -// insert code in reverse order. By convention waypoints intended for insertion -// before begin with 'End'. Notice below how the layers line up above the "End -// Foo" waypoint. -// -// File 001 File 002 File 003 -// ============ =================== =================== -// // Foo -// ------------ -// <---- :(before "End Foo") -// .... -// ... -// ------------ -// <---------------------------- :(before "End Foo") -// .... -// ... -// // End Foo -// ============ -// -// Here's part of a layer in color: http://i.imgur.com/0eONnyX.png. Directives -// are shaded dark. Notice the references to waypoints lower down in this -// file. -// -// Layers do more than just shuffle code around. Past the initial skeleton of -// this program (currently 00*-02*), it ought to be possible to stop loading -// after any file/layer, build and run the program, and pass all tests for -// loaded features. (Relevant is http://youtube.com/watch?v=c8N72t7aScY, a -// scene from "2001: A Space Odyssey".) -// -// This 'subsetting guarantee' ensures that this directory contains a -// cleaned-up narrative of the evolution of this codebase. Organizing -// autobiographically allows a newcomer to rapidly orient himself, reading the -// first few files to understand a simple gestalt of a program's core purpose -// and features, and later gradually working his way through other features as -// the need arises. Each step should be as simple as possible (but no simpler). -// -// Programmers shouldn't need to understand everything about a program to hack -// on it. But they shouldn't be prevented from a thorough understanding of -// each aspect either. The goal of layers is to reward curiosity. +//: You guessed right: the '000' prefix means you should start reading here. +//: +//: This project is setup to load all files with a numeric prefix. Just create +//: a new file and start hacking. +//: +//: The first few files (00*) are independent of what this program does, an +//: experimental skeleton that will hopefully make it both easier for others to +//: understand and more malleable, easier to rewrite and remould into radically +//: different shapes without breaking in subtle corner cases. The premise is +//: that understandability and rewrite-friendliness are related in a virtuous +//: cycle. Doing one well makes it easier to do the other. +//: +//: Lower down, this file contains a legal, bare-bones C++ program. It doesn't +//: do anything yet; subsequent files will add behaviors by inserting lines +//: into it with directives like: +//: :(after "more events") +//: This will insert the following lines after a line in the program containing +//: the words "more events". +//: A simple tool will 'tangle' these files according to the directives, though +//: it'll drop these comments starting with a '//:' prefix that only make sense +//: in the context of layers. +//: +//: Directives free up the programmer to order code for others to read rather +//: than as forced by the computer or compiler. Each individual feature can be +//: organized in a self-contained 'layer' that adds code to many different data +//: structures and functions all over the program. The right decomposition into +//: layers will let each layer make sense in isolation. +//: +//: "If I look at any small part of it, I can see what is going on -- I don't +//: need to refer to other parts to understand what something is doing. +//: +//: If I look at any large part in overview, I can see what is going on -- I +//: don't need to know all the details to get it. +//: +//: Every level of detail is as locally coherent and as well thought-out as +//: any other level." +//: +//: -- Richard Gabriel, "The Quality Without A Name" +//: (http://dreamsongs.com/Files/PatternsOfSoftware.pdf, page 42) +//: +//: Directives are powerful; they permit inserting or modifying any point in +//: the program. Using them tastefully requires mapping out specific lines as +//: waypoints for future layers to hook into. Often such waypoints will be in +//: comments, capitalized to hint that other layers rely on their presence. +//: +//: A single waypoint might have many different code fragments hooking into +//: it from all over the codebase. Use 'before' directives to insert +//: code at a location in order, top to bottom, and 'after' directives to +//: insert code in reverse order. By convention waypoints intended for insertion +//: before begin with 'End'. Notice below how the layers line up above the "End +//: Foo" waypoint. +//: +//: File 001 File 002 File 003 +//: ============ =================== =================== +//: // Foo +//: ------------ +//: <---- :(before "End Foo") +//: .... +//: ... +//: ------------ +//: <---------------------------- :(before "End Foo") +//: .... +//: ... +//: // End Foo +//: ============ +//: +//: Here's part of a layer in color: http://i.imgur.com/0eONnyX.png. Directives +//: are shaded dark. Notice the references to waypoints lower down in this +//: file. +//: +//: Layers do more than just shuffle code around. Past the initial skeleton of +//: this program (currently 00*-02*), it ought to be possible to stop loading +//: after any file/layer, build and run the program, and pass all tests for +//: loaded features. (Relevant is http://youtube.com/watch?v=c8N72t7aScY, a +//: scene from "2001: A Space Odyssey".) +//: +//: This 'subsetting guarantee' ensures that this directory contains a +//: cleaned-up narrative of the evolution of this codebase. Organizing +//: autobiographically allows a newcomer to rapidly orient himself, reading the +//: first few files to understand a simple gestalt of a program's core purpose +//: and features, and later gradually working his way through other features as +//: the need arises. Each step should be as simple as possible (but no simpler). +//: +//: Programmers shouldn't need to understand everything about a program to hack +//: on it. But they shouldn't be prevented from a thorough understanding of +//: each aspect either. The goal of layers is to reward curiosity. // Includes // End Includes @@ -102,5 +105,5 @@ void setup() { // End Setup } -// Without directives or with the :(code) directive, lines get added at the -// end. +//: Without directives or with the :(code) directive, lines get added at the +//: end. |