A long time ago, in a county far, far away, I had a gig that didn't pay well, and it was boring. As a result, I spent a lot of my time trying to unfuck Wikipedia...
And before I go any further, allow me to point out that although I usually select an image that is at least tangentially and conceptually related to the subject matter of my articles, I just thought this Mustang was sexy.
Where were we? Oh, yes. Wikipedia.
Wikipedia is effectively crowd-sourced bullshit. It represents a great way to hunt down citations for other sources in order to then hunt down citations for real sources, but beyond that it has very little value except as a barometer of what the average know-it-all knows about a given subject. There are, however, gems to be found within the endless tons of mud. Back in about 2008 or 2009, I happened upon one such gem.
Thanks to a case of near-terminal boredom (my boss at the time actually wrote me a letter of recommendation for my next job wherein he warned, essentially, "don't let him get bored"), one of the things I did at my job was fix terribly-worded articles on Wikipedia. Actually, I started out trying to improve articles by actually doing what the little template at the top says they want you to do (you know, find sources, remove inaccurate information, etc.), but I quickly discovered that those are outright lies and that every article on Wikipedia looks exactly the way its mother wants it to look.
I also learned that every article on Wikipedia has a mother: someone whose obsession with the article is somewhere between "inappropriate" and "I'm getting a restraining order" and who will basically burn you at the stake if you should happen to modify it. Am I digressing? Yeah, ok. Sorry.
So, instead, I thought I might hone my writing abilities (I have a degree in this, you know) by copy editing any article I found interesting. Things I find interesting are normally at the intersection of the technical, the historical, and the dramatic. Guns, tanks, ships, and planes are perfect examples, and the article on the Russian T-26 light tank, a derivative of the British-built Vickers 6-ton, seemed to me the perfect combination of captivating narrative, mind-numbing minutiae, and garbled diction on which to ply my trade. Over the course of two or three days, in between customers, I rewrote practically the entire thing.
The article was wonderful. Clear, colorful, concise... I had this fantasy that I might submit it for some kind of award. They have those kinds of things. God knows why. What I'm saying, though, is that it was good work. I hadn't provided the sources or the information, but I had made it interesting again. Unfortunately, that didn't last even a week.
It turned out that the Eastern European tank anorak (that parses two ways and both are probably correct) who had originally written the article was still paying attention. Thankfully, he seemed to enjoy my work, or at least he didn't revert anything. However, just as soon as the article began to make sense once more, he started adding to it.
His work hadn't made much sense in the first place, but the amazing thing is that it actually got worse as the two of us began to engage in a sort of strange, cooperative duel with the article as our battleground. It almost seemed that he was intentionally dumping barely-formatted information and sources onto the page with the intention that I would find some way to make it work as an article. Had this been a paid effort on my part, he might have gotten an excellent little monograph out of it a la The Complete Tankspotter's Guide to the T-26.
I didn't have that kind of patience.
Over the next week or two, I continued to watch what happened to the article, and I observed that he would continue to add data to any given section until that section reached some threshold of incomprehensibility. To wit, he stopped adding things when he could no longer see where to add them.
The same exact damn thing will happen every time you rewrite, refactor, or improve any given method in any given codebase on any given Sunday. Or, if your job has a little better work/life balance (why is work first?), it's more likely you're doing this stuff on a weekday, but let's get back to the matter at hand...
Software engineers, and I should state explicitly that this applies to all of us, will add features and functionality to a given bit of program code until we can no longer see a place to tack on the next cool thing. At that point, we rewrite it. Hell, this even applies to fancy copy editors like me: I will cram any passage in my work as full of wonderful things as I can, only stopping when I can no longer fit in anything good. There are only two factors that separate the good from the bad and the ugly:
- How much can you fit?
- Do you really know when to stop?
Greater skill means that your threshold of "can't fit anymore" will be pushed out closer to the horizon. In the ideal case, the boss man will run out of features before you run out of reach, in which case you wind up with a well-considered, adaptable product that does what it needs to do without making the programmer's head spin. This product, by the way, does not exist.
As far as knowing when to stop is concerned, it's basically out of our hands as engineers. The boss man will tell us when to stop, and the answer is usually some variation on the kind of thing your football coach said back in high school: "You can stop when I get tired!" The only real way to get around this is to continually layer in additional abstractions in order to maintain your threshold of minimum readability.
Of course, abstraction itself is an impediment to readability... But at least now you know why code never works.