

All the Ganglia. The Nerves. On leaving a programming project unfinished. - blu3jack
http://blog.overclocked.com/2012/07/07/all-the-ganglia-the-nerves/

======
blu3jack
And a great way to procrastinate from tackling the next leg of the project is
to blog about it, post a link to that blog on hacker news, and then
obsessively watch yourself bounce around the hacker news front page on a slow
Saturday afternoon.

------
follower
The single biggest thing that's helped me context switch between projects (or
return to one) has been keeping a project log.

To me, a project log is to documentation as Twitter is to blogging--it
requires little effort but over time provides useful pointers to where you
were at the time.

Originally I used a "one way personal wiki" to keep track, like this:
<http://code.rancidbacon.com/ProjectLogArduinoUSB>

But when I lost the server it was on I decided to re-implement it on Google
App Engine and make it available to other people, thus was born Labradoc,
here's an example project log: [http://www.labradoc.com/i/follower/p/project-
sms-text-scroll...](http://www.labradoc.com/i/follower/p/project-sms-text-
scroller)

It's kinda a "commit log for your day".

~~~
trafficlight
This is very cool. I hate coming back to a project a couple months later and
having no idea what state things got left in.

~~~
follower
Thanks. :)

Yeah, it's really helped with those "now, what was that command line I used?"
and "how did I solve that problem last time?" type questions too.

And not just for yourself. It also helps other people pick up "incomplete"
projects you might have lying around that you _cough_ haven't got around to
documenting yet.

------
orta
I've always found that talking to people that actually use a project as an
inspiration to keep working on things. That and find small ways to measure
progress. Get something small and working out then iterate fast.

------
ricardobeat
That sounds like a perfect counter-example to literate programming. All those
thoughts and decisions could've been documented in the code.

~~~
blu3jack
Perhaps, although most examples of literate programming that I have run into
tend to be so verbose as to be equally daunting and off-putting in a
completely different way. Another great topic: the art of the comment!

~~~
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...](http://github.com/akkartik/wart/compare/587e30dc51...8da3d3cf59)

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

