wart

I often run git blame to track down and reread old commit logs. But yeah the new codebase kinda dilutes the point because I'm changing so many things at once. It's an exercise in making a codebase as self-documenting and approachable to outsiders as possible in a variety of ways. The numbered filenames are one example. Each file is intended to be self-contained, and later files build on earlier ones. No need to hack on makefiles to add a new file. Just create it, number it right, and it'll get compiled, with access to everything in earlier files. Since this is a lisp interpreter the ethos translates to lisp functions as well. I can improve performance by deleting a lisp function, reimplementing it in a new .cc file, and restarting the interpreter. The interpreter will transparently run make, which will transparently compile the new file.

Yeah now it just goes into the commit log. The 'training wheels' were useful to get myself committing more frequently. Here's a kinda-random sample from my current obsession: http://github.com/akkartik/wart/compare/587e30dc51...8da3d3c...

I actually have a toy interpreter that does this: http://github.com/akkartik/wart#readme

I use tests for documentation. They seem like more work at the start, but they're more flexible. You can self-document things with tests that you cannot with just types. For example, here are some tests from the lisp interpreter I've been working on: http://github.com/akkartik/wart/blob/8a8cf96816/030.test You're right that tests aren't close to code. But that can be good or bad. Since it's not next to the code it can be more verbose and thorough without adding a constant reading burden. And when I wonder, "why is this line here?" I can comment it out and run the tests to find out. I think of tests as records of the input space of my program. Most of the time we go to great lengths to make explicit what we do but not quite what aspects of its behavior we truly care about. Where are the dont-cares in this program? If I refactor it am I res

Nice to meet ya! I've been working on a lisp as well: http://github.com/akkartik/wart#readme

It's easier to understand five simpler patches if 'diff' is too stupid to render the more complex patch. "Here I renamed this variable, then I moved this hunk over there, then I made the change." Even aside from the artifact of diff, I don't think this situation is analogous to short functions at all. The big difference is that commit logs are much more serial in nature. If I break one commit down to a sequence of 5 simpler commits they will almost always be read in that order, with context preserved. I'm ambivalent about long functions, but am much more draconian about complex commits: http://github.com/akkartik/wart

> You can implement a macro system in 30 lines of Lisp. All you need is read, and it’s easy. The linked pastebin isn't a macro system. It's merely a macroexpansion system, it needs to be evaluated. And it's not as simple as merely wrapping it in 'eval' because of subtleties in getting at the right lexical scope. More generally, no fair claiming macros are easy because you managed to build them atop a lisp. You're using all the things other comments here refer to; claiming it's all 'read' is disingenuous. I'm still[1] looking for a straightforward non-lisp implementation of real macros. The clearest I've been able to come up with is an fexpr-based interpreter: http://github.com/akkartik/wart [1] From nearly 2 years ago: http://news.ycombinator.com/item?id=1468345

I agree with your premise: "..we route around the damage and encapsulate it away inside our own APIs. ..if a system API is good enough, then we don’t need a library." ..but don't see how it leads to your conclusion: "Since APIs are guaranteed to be flawed, let’s accept that and work on encapsulation. Let’s replace authority with merit." Instead, my reaction is to be anti-abstraction and anti-backwards-compatibility. "Don't get suckered by interface guarantees; debug code." Implications: a) As a library/platform builder, I tell my users I make ZERO guarantees of backwards compatibility. I release no version numbers, only commits that they can pull if they want. If you build on my code, write tests or God help you. b) As a library user, I am extremely conservative about introducing new dependencies. When I do I pull it in once, write lots o