Simple Design

I like to keep my designs simple. I guess I have spent enough time poring over designs (or code) written by somebody else to have developed a soft heart for developers who have to maintain my work. Code that lacks comments, elegant algorithms that do not appear to really solve the problem (but somehow do, as if by magic), complexity in the name of simplicity, meaningless variable names. I am not unique; we have all encountered these phenomonon - often in our own code viewed just six months later. My whole criteria for good designs (and good code) revolves around one single question: How hard will it be for the average developer to maintain this?

Comments: It is 2002, do I really to discuss the how's and why's of commenting code? OK, 'nuff said.

Elegant Algorithms: I am all for elegance in a design, but it must be elegance that can be understood. I once worked with a developer who found a shortcut for navigating an XML DOM. I do not recall the actual shortcut; maybe something about finding the first sibling with a text element from any child. At any rate his solution was technically illegal - it was a non-supported feature and did not make logical sense. The code worked under MSXML 2.0, but failed with the 3.0 release of the parser. I like to keep it straightforward, even dumb it down. The solution should suggest the very problem being solved. Anything less and the design becomes too complex.

Complexity In The Name of Simplicity: I once led a team in the development of a disconnected web application. The whole thing ran out of IE's cache and relied heavily on client-side scripting, XML, and XSL to render the desired DHTML. We had one XML document that was displayed in three or four different places with only minor differences. A bright developer came up with the idea of representing each desired display using XML (e.g. column names, widths, XML tags to map into a column, etc.), then used an XSL transform (this was before Microsoft supported XSLT) to render the actual XSL required to yield the DHTML. It was very nice if you were only adjusting column names or widths. It performed terribly through and was a living nightmare to change. After making changes to the first XSL stylesheet a couple of times I finally got fed up and asked another developer to rip out the whole design and start over with four separate XSL transforms. Yes, they were all almost identical (hinting at quadruple maintenance), but it was a lot easier than trying to figure out how one XSL transform was emitting another XSL stylesheet.

Meaningless Variable Names: The naming of things is so incredibly important. A name tells us something about the thing named. It is more than just a tag, it is a story. The Ent's in JRR Tolkien's The Two Towers have names that tell their whole life story. It can take Ent's entire days to introduce themselves! We will put this at one extreme. I have worked with developers who are at the other extreme. Some, in a hurry to write code without bothering to think about how they are going to solve a problem start making up variable names: junk1, junk2, junk3, ... Some use vanity variable names: terry1, terry2, terry3, ... I worked with one that wrote a component enabling client javascript to manage XML documents in the local file system. He named it: XMLFile. I opposed this name, but did not force him to change it - a decision I quickly regretted. He felt he simply could not come up with a better name, so he named it after the data it worked on as opposed to what it did. Microsoft later shipped a component of the same name which only generated more confusion for the poor souls that had to maintain that application. I like variable names that reflect their purpose. If they are truly general purpose (parms in a utility routine), they should be simple, one or two-letter names that reflect their type.