Monday, August 10, 2009

Gifts to your future self

In my last blog post I took a look at the contents of a 13 year old archive of my doctoral work that was stored on a DOS formatted floppy disk.

My thesis was interesting, but more interesting were the READ.ME files that I'd scattered around the disk pointing out important information about what was stored on the disk, and how to interpret it.

These notes were gifts to my future self. In 1996 I left these READ.ME files knowing that sometime in the future I would open this disk and not know what to do with the contents.

A couple of these files were substitutes for symlinks. Since I was taking the files from a SunOS system and writing it to a DOS floppy in a ZIP file I lost two important things: symlinks and long file names.

In one directory a file called MACROS contains the text: Should point to ..\THESIS\MACROS. Copying to Mac OS X system and fixing the symlinks makes things work swimmingly.

Another READ.ME file explained how I had shortened some file names to fit into the 8.3 naming scheme:

TBD.TEX = thesis.bibliography.definition.tex
TD.TEX = thesis.definition.tex

These short comments were all that I needed to get my thesis up and running in LaTeX again.

This is pretty much the strategy that I apply to code comments: those comments should point out the things you are going to forget and are going to need to know in the future. Don't comment things that can be easily derived from the code. But bear in mind that you are writing comments for someone who is unfamiliar with the code base: you in a few days, weeks, months or years time.


tjp said...

8.3 you mean..

martijn said...

I totally agree with you about adding comments, but, while I keep telling myself to do it better from now on, for some reason I lack the self-discipline to do it properly. Most comments are added later on, after tidying the file, if they are there at all.

Perhaps not quite coincidentally, my doctoral thesis's README file says "should have long been finished".