organization

Here's a picture of my backpack: http://i.imgur.com/2pCqs.jpg

It's transparent so I always know what's in there, and where everything is.
There's no pockets where something can be misplaced. I like to keep everything
close at hand. If it's not that important, maybe I can get rid of it. This
codebase reflects the same aesthetic. Everything needed to build it (besides a
vanilla OS install) is in a single directory. Nothing is squirrelled away or
hidden under the carpet in a library path.

The files are organized to orient a new reader. Start reading the first file
you see, and then the next, and so on. Each file should make sense in
isolation, with just a high-level sense of previous files.

  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)

Each file comes with its own tests. To understand an unfamiliar name, read its
tests. If you see something weird in code, comment it out and see what tests
fail.

C often has extra constraints in ordering code. This codebase sidesteps many
of them by autogenerating various lists during compilation. There are lists of
files to compile, tests to run, Wart's compiled primitives. You can start
writing code in a new file, and it'll be compiled in as long as it starts with
a numeric prefix and has the right extension (.cc or .wart or .test). You can
create new C test functions anywhere as long as they start with 'test_', and
they'll run when you run 'wart test'. Function prototypes are autogenerated;
you can create new functions anywhere and use them anywhere.

The autogenerated lists are simple-minded. I don't try to parse all of C++ to
locate functions starting with 'test_', nor do I try to handle all possible
functions. I assume function definitions lie on a single line. Such
simplifying assumptions are possible because they're internal details without
external consumers. They are useful because they minimize the amount of code
needed for such infrastructure.

Fewer constraints on code organization make it more likely that code
organization will stay true to reality, with related code staying together,
and unrelated code staying apart.

Next: 002main.cc (https://github.com/akkartik/wart/blob/master/002main.cc)

Give feedback: wart@akkartik.com