1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
|
//: 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
// Types
// End Types
// prototypes are auto-generated; define your functions in any order
#include "function_list" // by convention, files ending with '_list' are auto-generated
// Globals
// End Globals
int main(int argc, char* argv[]) {
// End One-time Setup
return 0; // End Main
}
void setup() {
// End Setup
}
//: Without directives or with the :(code) directive, lines get added at the
//: end.
|