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