Thursday, April 5, 2007

Undocumented builds and backwards incompatibility

So I spent a lot of yesterday trying to, without any documentation at all, build a Windows executable out of a Python program whose GUI is based on an older version of Qt/PyQt. Unfortunately PyQt 4 is apparently NOT backwards-compatible with PyQt 3, such that the existing scripts would not work with PyQt 4 as they were written. It was an absolute nightmare getting the older versions compiled, installed, and working, and it made me want to document some general thoughts.

My primary function has never been as a developer, but I've still always written code as part of my job responsibilities. People like me (and like the person who wrote the Python program, I imagine), don't generally have the same experience in formal software development processes as "Computer Programmers (TM)". This tends to cause problems.

The interesting thing is that the problems seem to come from dependencies, building, and things of that nature than with the code itself. I think most of the actual code I write, and a lot of the code of this sort that I've read, is more or less self-documenting. I'm talking mostly about utility programs, generally less than 1000 lines and often less than 250 lines.

Notes to self, and other interested parties:
  • Document your build process if it's anything more complicated than "cc file.c". (I will be forever in your gratitude if you leave me a Makefile.)
  • Use some sort of central code repository. Digging through backups of old PC's to recover code is no fun for anyone.
  • Related: don't just leave your code, if at all possible...leave the libraries, utilities, and other related items somewhere where I can find them. At worst, leave me links to go get them.
  • Create a README file! If you have to solve any problems or come across anything quirky, NOTE THEM IN THE README!
  • A function called "GetUsername" does not need a comment that reads "Gets the username."

  • Thomas Ptacek is writing a great series of arguments against DNSSEC over at the Matasano Chargen blog. That's one of my favorite blogs, by the way, and I highly suggest that anyone in information security make it a daily read.
  • I don't have anything to add about the ANI vulnerability (MS07-017), other than to wonder when we're going to stop seeing this kind of thing. Weren't we doing this with WMF at this time last year?
  • I have thoughts on Fortify's interesting JavaScript hijacking "Web 2.0" advisory, but I think I'll write a separate post 2.0 on that subject 2.0.
  • The Blogger "Compose" interface is terrible. What should I be using instead? Should I just use a text editor and then paste it in?

No comments: