Anthony Panozzo's Blog

On a long enough time line, the survival rate for everyone drops to zero.

Chuck Palahniuk, Fight Club

In the long run, every signal dies. Paper rots, genes mutate, forests burn, files corrupt. Error correcting codes help, but they aren't enough. Perfect preservation of effort is not the way of the universe. Human languages evolve and break down meaning.

Will my personal journal be lost in an accident following the poisson distribution within my lifetime? Will my grandchildren care enough to translate my life's work to the technology of the day before it is unreadable? There is a difference between preservation and the ability to understand, as Robert Scoble points out.

My friend Tyson works at a major insurance company. Recently he shared with me a technique that he uses there: He keeps a work journal to write down domain-specific things that he learns.

Journaling could include writing down a technique or rule of thumb used, a page of a book that was helpful in a certain area, or who to contact in a different department in case of questions in a specific area. Sometimes it could be something that went particularly well so that he can look back when times are tough and remember a time when he persevered. Other times it is something that didn't go as well as he hoped. He also does this to clarify his own knowledge so that when he needs information he has a place to look, and for potentially transferring that knowledge to other people.

I recently tried experimenting with this technique. I suppose that I like writing, so this came somewhat naturally. I liked separating this from other writing that I do because it seems useful to have it all in one place. I am just capturing knowledge that I have gained from working on a project. Writing this down regularly is really helpful in writing documentation later because you explicitly state what you have recently learned. This prevents me from being blinded to what I learned and taking it for granted. It might be obvious to me at the end of a project why the build works the way that it does, but along the way I needed to learn a lot of things and make various decisions. So this seems to be a good way of documenting decisions for later understanding and analysis of results.

I've noticed that when developers have worked on a project and then someone else takes it over, they seem to feel guilty about decisions made on the project. When I ask them why certain decisions were made, they might sheepishly say, "Yeah… I know it's not the best way to do this, and it's not the way I would do it now." Some might get defensive, or cite external constraints like schedule pressure. But my belief is that developers should not feel strongly negative about older projects.

Experience

I'll admit that I got a mulligan. It was a Ruby on Rails project for an internal tool. I hadn't worked with that technology stack much before. I kind of hacked something together based on the requirements, and it worked fine. There were few tests, and the design definitely did not use best practices. But it worked.

If you absolutely must complain, I have found an interesting, and perhaps socially acceptable, way to do this. There are a few concepts that separate my method from ordinary complaining.

Pecha Kucha

Pecha Kucha is a challenging presentation format where presenters have twenty slides shown for twenty seconds each. Presenters are forced to practice and consider what they will say and how they will transition between sections, and are promptly jerked off of the stage after their time is up.

Complaining

If you can change your situation, change it. If you can stop yourself from complaining, don't complain. Always consider these first and consider your underlying assumptions again. What seems out of your control is often in your control but outside of what you let yourself believe. Considering complaining about your relationship or your job or your house? What larger problems are under the surface, and what can you do about them? Even if you don't believe you can change your situation, you can likely change your attitude about it.

I was wondering what people's standards for using tags in comments like TODO, FIXME, HACK, XXX, and the like were.

// TODO: implement the foo module here
...
// HACK here be dragons
...
// XXX
...
/* FIXME:  late at night, I need some sleep */
...

One advantage of using these tags is that they are easy to search for and give an understanding of where the code can be improved. Most IDEs even have a special view to look for these kinds of things.