I don’t talk much in these pages about my work, and that is perhaps the one sound, high-quality, survival-instinct-oriented decision I have ever made as a blogger. Don’t like to poop where I eat. Naturally, that is the one from which we shall backpedal today.
Volunteered the following during a very rare participation from Yours Truly on LinkedIn. By the way, if you work for a living and haven’t joined LinkedIn, do it today. I don’t care if you’re a construction worker, or embalmer/medical examiner, or sex worker. Great repository of all kinds of nuggets of information you can actually use.
Anyway, on the subject of writing quality code…
There are four tiers of quality code, and no I’m not going to cite my source because this is the product of personal experience.
1. I wrote it, it does what it’s supposed to do, I’m so glad we’ll never have to change it because I never want to look at it again. Just like getting done with this year’s taxes.
2. I wrote it, it does what it’s supposed to do, and if you want it to do something different I’ll be able to work in a new feature so fast it’ll make your head spin. But you’d better pay me whatever I want because woe be unto the poor dummy who takes over my job and has to spend the next two years getting “up to speed” with my variable names, class construction, indent style, lack of internal documentation, etc.
3. .I wrote it, and I made sure as I went along to stop and ask myself “If I was a new guy would I need to have this explained” and then I dutifully added the explanation. An experienced developer seeing this code for the first time shouldn’t have to fight too much to figure out how to address any documented defects and do more harm than good…although the expectations for “ramp time” should always be somewhat reasonable.
4. In an effort to acquire and maintain a certification for the ####.###.## standard and comply with the new AAAAAAAAA regulation that goes into effect next year, my company has gone through this code line-by-line and added documentation blocks wherever they are required. Which is everywhere.
I hasten to add there is a correlation between good internal documentation and easily-maintained code that is something like dolphins and fish and things that live in the sea…internal documentation, where it makes sense to have it, is required in order to make the code reasonably maintainable for anyone who doesn’t work with the benefit of personal design-to-implementation familiarity — but all “well” documented code is not necessarily maintainable. The internal documentation is just a tool, nothing more. Too much of it gets in the way. And if put on a new project, I would feel much better about things and do a better job justifying my paycheck if I were working on Tier 3 code than on Tier 4 code.
The composition of the code needs to be consistent in order for quality code to work its way up this tier-ladder. There is overlap between the requirements of the project, and the features to be used in the language(s); if that overlap is diminutive, it will be a challenge to produce quality, maintainable code because the software will be providing focus trying to bridge this gap between what the language provides and what the resulting application is supposed to do. A good architect therefore needs to leverage the strengths of the language, produce coding standards that implement this leveraging, and see to it they are enforced.
I see nowadays the languages have become so capable, that the responsible software architect needs to start making some decisions about what language features NOT to use. This is a somewhat new development, but I see a future in which it will become more and more necessary.
This touches on a beef I have had for a few years, and I think I wrote about it in these pages. Maybe I did and maybe I didn’t. However, if I had to guess about whether I did or not, I’m inclined toward the negative…so for now I shall not trouble myself with doing a search so I can provide a link. I think such a link does not exist. Could be wrong.
But here’s the itch I can’t scratch —
The trend I have been noticing is that software developers, together with the people on higher levels who have the responsibility of managing what they do, just love to bitch and piss and moan about how the code is not well documented. I find this to be reasonable, so far. Poorly documented code leads to questions where there should not be questions. People tie up their time asking the questions, then answering the questions, then misinterpreting the answers, then writing code based on the incorrect misinterpretations of the answers and then destroying the code and taking another crack at it — this all costs time. And therefore money. Copious amounts of both of those.
Now, when it is time to get together and discuss who’s excellent in this craft, versus who is simply mediocre, how is the rating done? Understandably, it is done according to who best facilitates an avoidance of the above frustrating and expensive cycle. And here is where things start to go awry: Software developers start to be evaluated in doublets, triplets, groups. If, when they get together, complex thoughts are syndicated quickly, reliably, and without error…this has the effect of bringing credit on each individual within that group, and if the pattern can be maintained then they will all feel a perceptible career boost out of it. Still and all, at this point all is fair. They are contributing to the bottom line of their respective employers and they are being plied with the rewards for that contribution. This is the essence of capitalism. Nothing wrong with that, huh?
But there is something wrong with it: Software developers, as a general rule, write down only what has become indispensably necessary to write down, and not a single word more than that. It is the work, you see; there is always more of it to be done, than the staff hours allotted to it.
When a group of them enjoy all the benefits attendant to belonging to one of these tightly-knit grouplets, and the demand for their services starts to exponentially ascend due to this success — the first thing that happens is shit doesn’t get written down. Where’s the necessity? Where’s the incentive? Both are gone.
Contrasted with that, if you get two teams together who don’t speak the same way, but they absolutely-positively have to learn how in order to get the job done…things get written down. It’s gotta be that way. This team over here is accustomed to counting 1 to n, that team over there is accustomed to counting 0 to n-1. So before things start working, the technical documentation gets produced and it bears a distinct resemblance to exactly the stuff people bitch about when it’s not there. That’s the way things are supposed to work. But along the way, friction is produced, and with that there is some heat…and it brings discredit on the individuals on both sides of the divide.
So they end up not getting promoted. Even though they’ve gone through the real trials and tribulations of not just making things work, but defining how they need to work. In writing. Which has a bearing on bringing these solutions to market, effectively and profitably. Career-wise, though, they lose out to the “Furbies” who can syndicate with each other by these invisible beams, and because the Furbies can syndicate so effectively with each other, they end up pooling their resources toward the objective of making things actually work. Without writing anything substantial down. Producing, rather than documentation, a dearth of it. For people to bitch and piss and moan about later.
To distill all of the above down to its essentials — we say we want something, and then if you extrapolate what we want by who we promote and who we do not, what we “want” turns out to be the exact opposite of what we say we want. To distill it further — we seem to be laboring under the impression that if we promote those who show signs of this elusive “empathy,” all the pieces will somehow magically fall into place.
The tragedy is not far removed from the damage we are doing to ourselves in national politics, when we choose our leaders. So-and-so possesses this elusive ability to “communicate,” so if we choose that guy, all will be well and we won’t even have to mess with any of the details to make things well.
It’s a fool’s dream.
And as far as software development is concerned, the case can be made that the greatest talent is to be pooled up in those who possess shitty communication skills…at least, when one confines one’s inspection to those who have successfully delivered on the things they were building. After all, the people with shitty communication skills were forced to define the details so they could get them properly communicated, were they not? They had to break things down to their essentials, which means, they had to understand those essentials. The “brilliant” communicators didn’t have to do this, they were able to achieve the right “vibe” about such things, in wholesale, without breaking anything down…so they weren’t forced to comprehend all the atomic elements.
I should mention they probably did understand such things, at some level. To achieve a mastery of both human communication and technical nuts-and-bolts, is not a negligible task by any means. These are very bright people. Very bright. We’re talking Mensa stuff here. They can probably whip the ass of anyone you can care to name at a game of chess.
But if it’s about business — you get a more valuable asset, at the end of it all, if you task people or groups of people who are required to define things down to the inseparable atomic parts, before things start working. It might not seem like it at first, because more time is put in during the initial stages and there’s little payoff for it.
But my point is proven when people start bitching away about the lack of documentation.
It is proven, even further, when developers start leaving the project and have to be replaced. All the “Furby” benefits of these sociable Mensa chess-player types communicating on their invisible beams…they are histoire. What’s being missed is that the method of syndication is endemic to the genius types conducting it. They move on, it moves on. And this is not a concern easily dismissed. The nature of genius is that it isn’t like mediocrity; it is way down at the far side of the bell curve.
Let’s be clear on my meaning here: This is not advice to profile people. We’re all trying to make a living, and whether they benefit from the invisible beams of the “Furbies” or not, has no correlation against the honesty of the associates working to earn the paychecks or the lack thereof. At least, no correlation upon which I will comment here.
The point is that when people communicate in whatever form, it is a messy process. Things don’t get defined any more specifically than they have to be. My advice, therefore, has to do with treating the developers the way a responsible tester treats the elements in a test script: Build according to the worst-case scenario. On purpose. At least some of the time. If you work too efficiently at it, you’re not getting the job done. Do it so you get those specifics.
The specifics, in the final analysis, are where the money is. It is an information business. The information, therefore, is where the gold sits — whether the stakeholders keep this in mind or not.
folks have speculated this has to do with a gun permit. Not quite. It’s a u-turn sign; I haven’t blogged about this, but since the twentieth of June I have been obsessed with u-turn signs. That’s the day I got busted for disregarding one.
Well, the big day is here. Win or lose, I don’t expect this hearing will last more than a couple minutes; I’m just not that important. But everyone who knows me well enough to be forced to reckon with my day-to-day life-happenings is expressing more than a casual interest in how this thing is going to turn out; truly a case of an irresistible force meeting up with an immovable object.