//: 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") //: ....