[akkartik]

I prefer to record design decisions not inline in code comments but in my git commit log. Design decisions are best viewed as a chronological big-picture conversation with myself as I try out different things. I also find them to be just concise enough.

I don't use it anymore, but this was how I got started on this approach: http://akkartik.name/codelog.html

[blu3jack]

Thanks for the link, that's pretty interesting. Do you use a modification of this now, or have you simply codified that approach internally and commit intuitively?

[akkartik]

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...

[blu3jack]

Seems ok. Not sure it's the "answer" to making sense of a codebase, but it's certainly addresses part of the problem. Why do you number your files, e.g. 003parse.cc?

[akkartik]

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. And tests on the lisp function will continue to pass if I did the translation right.

There's a README (http://github.com/akkartik/wart#readme) that tries to convey my goals, but I haven't had too many people read it yet. I'd love to hear what isn't clear. You aren't supposed to know lisp to understand it.