Leaving Crumb Trails -- Talking to Myself

The past me is another person. Sometimes antagonist, sometimes friend, past me (postaction?) had ideas, hopes, and dreams and developed some of them into software that I and others use. Unfortunately, that asshole left bugs all through the code for me to fix.

I can't blame him. Nobody's perfect, not even idealized/demonized copies of my past self. But I do have to fix them, and deal with the messes he left.

Lucky for me, while he was writing buggy software, he left extensive notes for me to use...

At the highest level, when all memory of the project is lost, past self left detailed documentation describing the what and why of the code. Without getting bogged down in the code, I can usually track down some likely sources of my current problem.

=head2 find_files()

Find the files in this Store. Returns an iterator that generates Path::Tiny objects
suitable to be passed to read_file() or open_file()

=cut

Once the docs have refreshed the memories of past me, I can start looking at the code. By keeping the docs near the code, past me left hooks all over for me to latch on to. If I search for the name of the method, or just a key word of its behavior, I find the code I'm looking for.

Eventually, I'll come to the buggy part. Instead of just changing the code and fixing the bug, I wonder about why that code was written. Past me was a smart guy. Not as smart as me, but I've learned not to second-guess him without due diligence. So, I'm relieved when I can check the commit log to find the reasons why this line of code exists in exactly this way. Past me has a habit of writing at least a paragraph about the change, why it was necessary, and ideas for future enhancements or complications.

commit e084118b88e3838e38d5afa027d770ab22ca9903
Date:   Mon Dec 22 04:15:45 2014 -0600

open/write filehandles using raw bytes

When the Static app would read/write an image, we would get a bunch of
warnings of characters not mapped to UTF-8. Now, if we're using a
filehandle, we assume raw bytes.

Also added some notes in the docs about how encodings are handled. We
can't just silently try to Do The Right Thing. We need to tell the
developers what we're doing so that they can figure things out when they
go wrong.

Fixes #171

Sometimes, a commit is linked to a ticket tracker, which is another valuable source of information. Though the commit message told me about the final version of that change, past me jotted down notes, ideas, tests, user reports, potential solutions and the reasons for rejecting them. These weren't appropriate to gum up the commit logs with, but the ticket tracker is close enough to the code to be useful when more information is needed. I appreciate not having to sift through pages of text while I'm tracking down the source of a bug (that said, I'd prefer too much text to not enough).

The further away from the code, the more verbose past me is. He starts with the small clues, and if I figure it out, that's all I have to swallow. But if I can't figure it out, I can always find a bigger clue just a little further away.

Learning to work with past me has been a long struggle. He and I are constantly refining our pair programming practices. By writing myself good documentation explaining what and why a subroutine exists, I help myself remember what the code is for. By leaving detailed explanations and rationales in the commit log, I can remember why a change was made. By keeping user reports, brainstorming, and notes in a ticket tracker linked back to the commit, I can read about everything I was thinking when I wrote that code. Doing all this helps future me be an even better programmer than past me and I could imagine.