Artful Ownership

In a relationship-driven business world, job security and software maintainability are directly and inversely related. Gothically this happens both through a carrot and stick approach from the developer toward the management team and also from a developer to his own future self.

Promoting ownership stimulates the desire to create maintainable code. Much like the difference between renting an apartment and owning a house, the developer who recognizes that he owns (and is responsible for) the code has a vested interest in being able to go back years from now to understand how it works.

Management teams that swap out developers like machine cogs create a separation between a developer and his code: in essence the developer becomes a "renter" and he will deliberately obfuscate his work. One because he has no incentive to spend the extra effort to make it maintainable, and two because he will strive for job security by obscurity: he punishes the management for his insecurity by complicating their desire for robotic interchangeable developers.

In some cases though software may be a one-shot throwaway: if management expects the march of technology to obsolete a software platform rapidly then it might not particularly care whether it is maintainable. Hence if a developer would rather own than rent, he better darn well be sure that he works on creating a substantial and mission-critical system that his employer will still be relying on, with the same platform, six or seven years from now.

Yet... ownership is a chimera. It is an intentional feeling rather than an actual reality. Legally the developer does not own the fruits of his work. How can management promote the feeling of ownership even though the legal reality is otherwise? If it fails to do so it can never expect developers to create lasting platforms.

Artful Verification

Sometimes despite your desires to remain logical and analytical (you did after all choose to be a system design professional) you will find yourself in a position that requires you to pass judgment on others. This is never more true than when you are selecting a software package vendor. You have to be friendly but still cynical; vendors send you salespeople who know how to read your desires and make promises that cater to them. As a buyer you need to keep a critical eye toward what you know to be the facts.

Back in the early 1980s, when personal computers had 5 1/4 inch floppy disks and still went zyg zyg beep to start up, when ten megabyte hard disks were all the rage, I had the opportunity to review software vendors to provide hard disk security systems. The concern back then was that somebody could boot up from a floppy, switch to the C drive, and read all your data.

I was impressed by one vendor claiming that they not only could provide complete security, but actually prevent an unauthorized person from accessing the hard disk at all. As I had already reviewed the bios code and was familiar with how a computer loaded its bootstrap, I found their claim to be, eh, interesting. I asked to see a demo and they arranged for a salesman to drop by.

He gave a fairly nice demo, showing how their software could be configured so that only specific people could see certain files. at the end of the demo I commented "gee nice. Hey I was wondering about this item I read here about total protection." I told him that I seriously doubted their software could prevent somebody from destroying all the data on the C drive. He adamantly assured me that it would. Well then, was he confident enough that he would let me have a crack at his demo computer? Without a flinch he said sure!

I carried up a boot disk with the old DOS debug program on it, turned off his computer, put the disk in, and turned the computer on again. Zyg zyg beep! At the DOS prompt I typed debug and then used a command to write all zeroes to the boot sector on the hard disk. "Well uh, I think I just wiped your C drive," I shrugged. The salesperson didn't believe me. I removed my floppy disk and watched in a pitying amusement as he tried to restart his computer. Naturally the C drive was no longer readable at all (now he would have to reformat it). Needless to say we didn't purchase their software. Moral of the story: when you are buying software, trust... but verify.

Artistic Communication

Technical documentation is one of the least appreciated aspects of software development -- not the written words themselves, but the process of creating them is deeply undervalued. Effective technical documentation is like a Hail Mary pass from the developer in the present to the developer in the future with the intervening crosswinds of bug fixes and changes to the business rules complicating the reception.

The developer is usually the best person to author technical documentation: he understands the implicit trail of bread crumbs that he has already left in the code for somebody else to follow. If he was involved in the project from the start then he can also relate to the politics and priorities that the team faced from the design and implementation stages.

A technical document should begin with a Background section that describes the rationale behind the project and the challenges that sufaced during design and implementation. This should alert future developers to any political or technical potholes that they should avoid.

Next an Architecture section should briefly describe data flows, timing constraints, and security layout. Next some Entity Relationship diagrams: not the whole thing but just the key tables and their relationships. Then a high-level UML and quick use-case diagram, focusing on how employee responsibilities overlap with components of the system. Finally, reference the design specifications that can, at this point, direct the developer to the whole ball of wax.

Good technical documentation isn't extraordinarily deep or complicated provided that you focus on its main intent. Sure you understand the system (because you created it), but standing at the other end of the football field a future developer can easily get buried in minutiae. Wipe away those confounding crosswinds and throw that future developer a touchdown.