All the Ganglia. The Nerves. On leaving a programming project unfinished. | Hacker News Reader

All the Ganglia. The Nerves. On leaving a programming project unfinished.

blog.overclocked.com

45 pointsblu3jack15 comments

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.

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

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

I like it. I have done some things like this in the past, but not in as much detail as yours. Very inspiring!

Cheers. :) I have to admit as much as I would like everyone to use Labradoc, inspiring other developers to get in the habit of writing public project logs is a prime objective too--whatever they use.

I started out with just writing single line entries but because they proved so useful it encouraged me to spend a little more time writing longer entries. (Although I often end up with a whole bunch of browser tabs open as a result. :) )

When I've done it, I've done it as a status log at the bottom of the README, or in a separate file in the project. But I think your level of detail is just right: it doesn't look ridiculously time consuming, and yet it captures the real content & momentum of the project.

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.

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.

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.

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

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!

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

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?

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

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?

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.

Reply on news.ycombinator.com