|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Mu - 000organization.cc</title>
<meta name="Generator" content="Vim/7.4">
<meta name="plugin-version" content="vim7.4_v2">
<meta name="syntax" content="cpp">
<meta name="settings" content="use_css,pre_wrap,no_foldcolumn,expand_tabs,prevent_copy=">
<meta name="colorscheme" content="minimal">
<style type="text/css">
<!--
pre { white-space: pre-wrap; font-family: monospace; color: #eeeeee; background-color: #080808; }
body { font-size: 12pt; font-family: monospace; color: #eeeeee; background-color: #080808; }
* { font-size: 12pt; font-size: 1em; }
.Delimiter { color: #800080; }
.Comment { color: #9090ff; }
.Constant { color: #00a0a0; }
.Identifier { color: #fcb165; }
.Normal { color: #eeeeee; background-color: #080808; padding-bottom: 1px; }
.PreProc { color: #800080; }
-->
</style>
<script type='text/javascript'>
<!--
-->
</script>
</head>
<body>
<pre id='vimCodeElement'>
<span class="Comment">//: You guessed right: the '000' prefix means you should start reading here.</span>
<span class="Comment">//:</span>
<span class="Comment">//: This project is set up to load all files with a numeric prefix. Just</span>
<span class="Comment">//: create a new file and start hacking.</span>
<span class="Comment">//:</span>
<span class="Comment">//: The first few files (00*) are independent of what this program does, an</span>
<span class="Comment">//: experimental skeleton that will hopefully make it both easier for others to</span>
<span class="Comment">//: understand and more malleable, easier to rewrite and remould into radically</span>
<span class="Comment">//: different shapes without breaking in subtle corner cases. The premise is</span>
<span class="Comment">//: that understandability and rewrite-friendliness are related in a virtuous</span>
<span class="Comment">//: cycle. Doing one well makes it easier to do the other.</span>
<span class="Comment">//:</span>
<span class="Comment">//: Lower down, this file contains a legal, bare-bones C++ program. It doesn't</span>
<span class="Comment">//: do anything yet; subsequent files will contain :(...) directives to insert</span>
<span class="Comment">//: lines into it. For example:</span>
<span class="Comment">//: :(after "more events")</span>
<span class="Comment">//: This directive means: insert the following lines after a line in the</span>
<span class="Comment">//: program containing the words "more events".</span>
<span class="Comment">//:</span>
<span class="Comment">//: A simple tool is included to 'tangle' all the files together in sequence</span>
<span class="Comment">//: according to their directives into a single source file containing all the</span>
<span class="Comment">//: code for the project, and then feed the source file to the compiler.</span>
<span class="Comment">//: (It'll drop these comments starting with a '//:' prefix that only make</span>
<span class="Comment">//: sense before tangling.)</span>
<span class="Comment">//:</span>
<span class="Comment">//: Directives free up the programmer to order code for others to read rather</span>
<span class="Comment">//: than as forced by the computer or compiler. Each individual feature can be</span>
<span class="Comment">//: organized in a self-contained 'layer' that adds code to many different data</span>
<span class="Comment">//: structures and functions all over the program. The right decomposition into</span>
<span class="Comment">//: layers will let each layer make sense in isolation.</span>
<span class="Comment">//:</span>
<span class="Comment">//: "If I look at any small part of it, I can see what is going on -- I don't</span>
<span class="Comment">//: need to refer to other parts to understand what something is doing.</span>
<span class="Comment">//:</span>
<span class="Comment">//: If I look at any large part in overview, I can see what is going on -- I</span>
<span class="Comment">//: don't need to know all the details to get it.</span>
<span class="Comment">//:</span>
<span class="Comment">//: Every level of detail is as locally coherent and as well thought-out as</span>
<span class="Comment">//: any other level."</span>
<span class="Comment">//:</span>
<span class="Comment">//: -- Richard Gabriel, "The Quality Without A Name"</span>
<span class="Comment">//: (<a href="http://dreamsongs.com/Files/PatternsOfSoftware.pdf">http://dreamsongs.com/Files/PatternsOfSoftware.pdf</a>, page 42)</span>
<span class="Comment">//:</span>
<span class="Comment">//: Directives are powerful; they permit inserting or modifying any point in</span>
<span class="Comment">//: the program. Using them tastefully requires mapping out specific lines as</span>
<span class="Comment">//: waypoints for future layers to hook into. Often such waypoints will be in</span>
<span class="Comment">//: comments, capitalized to hint that other layers rely on their presence.</span>
<span class="Comment">//:</span>
<span class="Comment">//: A single waypoint might have many different code fragments hooking into</span>
<span class="Comment">//: it from all over the codebase. Use 'before' directives to insert</span>
<span class="Comment">//: code at a location in order, top to bottom, and 'after' directives to</span>
<span class="Comment">//: insert code in reverse order. By convention waypoints intended for insertion</span>
<span class="Comment">//: before begin with 'End'. Notice below how the layers line up above the "End</span>
<span class="Comment">//: Foo" waypoint.</span>
<span class="Comment">//:</span>
<span class="Comment">//: File 001 File 002 File 003</span>
<span class="Comment">//: ============ =================== ===================</span>
<span class="Comment">//: // Foo</span>
<span class="Comment">//: ------------</span>
<span class="Comment">//: <---- :(before "End Foo")</span>
<span class="Comment">//: ....</span>
<span class="Comment">//: ...</span>
<span class="Comment">//: ------------</span>
<span class="Comment">//: <---------------------------- :(before "End Foo")</span>
<span class="Comment">//: ....</span>
<span class="Comment">//: ...</span>
<span class="Comment">//: // End Foo</span>
<span class="Comment">//: ============</span>
<span class="Comment">//:</span>
<span class="Comment">//: Here's part of a layer in color: <a href="http://i.imgur.com/0eONnyX.png">http://i.imgur.com/0eONnyX.png</a>. Directives</span>
<span class="Comment">//: are shaded dark.</span>
<span class="Comment">//:</span>
<span class="Comment">//: Layers do more than just shuffle code around. In a well-organized codebase</span>
<span class="Comment">//: it should be possible to stop loading after any file/layer, build and run</span>
<span class="Comment">//: the program, and pass all tests for loaded features. (Relevant is</span>
<span class="Comment">//: <a href="http://youtube.com/watch?v=c8N72t7aScY">http://youtube.com/watch?v=c8N72t7aScY</a>, a scene from "2001: A Space</span>
<span class="Comment">//: Odyssey".) Get into the habit of running the included script called</span>
<span class="Comment">//: 'test_all_layers' before you commit any changes.</span>
<span class="Comment">//:</span>
<span class="Comment">//: This 'subsetting guarantee' ensures that this directory contains a</span>
<span class="Comment">//: cleaned-up narrative of the evolution of this codebase. Organizing</span>
<span class="Comment">//: autobiographically allows a newcomer to rapidly orient himself, reading the</span>
<span class="Comment">//: first few files to understand a simple gestalt of a program's core purpose</span>
<span class="Comment">//: and features, and later gradually working his way through other features as</span>
<span class="Comment">//: the need arises.</span>
<span class="Comment">//:</span>
<span class="Comment">//: Programmers shouldn't need to understand everything about a program to hack</span>
<span class="Comment">//: on it. But they shouldn't be prevented from a thorough understanding of</span>
<span class="Comment">//: each aspect either. The goal of layers is to reward curiosity.</span>
<span class="Comment">// Includes</span>
<span class="Comment">// End Includes</span>
<span class="Comment">// Types</span>
<span class="Comment">// End Types</span>
<span class="Comment">// prototypes are auto-generated in the makefile; define your functions in any order</span>
<span class="PreProc">#include </span><span class="Constant">"function_list"</span> <span class="Comment">// by convention, files ending with '_list' are auto-generated</span>
<span class="Comment">// Globals</span>
<span class="Comment">// End Globals</span>
<span class="Normal">int</span> main<span class="Delimiter">(</span><span class="Normal">int</span> argc<span class="Delimiter">,</span> <span class="Normal">char</span>* argv[]<span class="Delimiter">)</span> <span class="Delimiter">{</span>
atexit<span class="Delimiter">(</span>teardown<span class="Delimiter">);</span>
<span class="Comment">// End One-time Setup</span>
<span class="Comment">// Commandline Parsing</span>
<span class="Comment">// End Commandline Parsing</span>
<span class="Identifier">return</span> <span class="Constant">0</span><span class="Delimiter">;</span> <span class="Comment">// End Main</span>
<span class="Delimiter">}</span>
<span class="Comment">//: our first directive; will move the include above the program</span>
<span class="Delimiter">:(before "End Includes")</span>
<span class="PreProc">#include</span><span class="Constant"><stdlib.h></span>
<span class="Comment">//: Without directives or with the :(code) directive, lines get added at the</span>
<span class="Comment">//: end.</span>
<span class="Delimiter">:(code)</span>
<span class="Normal">void</span> setup<span class="Delimiter">()</span> <span class="Delimiter">{</span>
<span class="Comment">// End Setup</span>
<span class="Delimiter">}</span>
<span class="Normal">void</span> teardown<span class="Delimiter">()</span> <span class="Delimiter">{</span>
<span class="Comment">// End Teardown</span>
<span class="Delimiter">}</span>
</pre>
</body>
</html>
<!-- vim: set foldmethod=manual : -->
|