Reality Denied

Some Thoughts on Contract-First Design

2019-05-08T01:00:00-05:00

One of my current projects involves creating a contract for a new web service-based API. We’re starting from scratch and developing a code-free¹ contract² prior to development. I’ve been involved, in one way or another, in the development of many web services and, of course, we never got too deep into the code without some broad understanding of what would be provided in the contract. The line between contract design and construction was much blurrier in most cases. We would start with some general understanding, someone would write some classes for the endpoint, everyone would start coding and stuff would get changed along the way.

All good fun, very agile, but, at the same time, not very close to contract-driven design - at least in theory.

When you stop and think about it, you realize that a heavy contract-first approach to building web services is very waterfally. It emphasizes documentation, process and the idea that a finished design can be sort of kicked down the hall to someone responsible for coding it up.

One colleague pointed out to me that the greatest success we had with sort-of contract first design came on one of our first projects together. I was doing user interface work and he was doing the backing web services. The architect on the product handed us a design he had sketched out. It wasn’t fleshed out or anything, but it represented a good starting point. We tweaked it a bit, filled in the gaps and started coding against it, each in a different language. The contract itself was an XSD document that was used to generate classes in Java and C# for the different components.

This sounds a lot like a contract-first paradise and, in that sense, I think contract-first has a lot to offer in terms of forging a basic consensus about what is going on. What differentiates that from a lot of contract-first theory is that we - the two who hammered out the final contract - sat next to each other throughout the project. We tweaked it to handle UI needs and to handle integration needs on the service side. We had a document of the contract, in the form of that little XSD, but it was a living contract.

I’m open, of course, to the idea that there is some selection bias here. It is all from my experience, which means that I was involved and my quirks and idiosyncrasies played out in each case. The most important thing is that I’m getting to try out something I don’t do as much and that’s a big part of what keeps us fresh. I look forward to doing something of a post-mortem on this project once it settles into production usage.

A pedant would argue that, at some point, the contract that is used to generate classes is no different in the end than code written in Java or C# to create classes - but we none of us are pedants, are we? ↩
The contract is in OpenAPI (Swagger) 3, a matter of future historical interest only. ↩

The Kinds of Technical Diversity

2019-04-24T01:00:00-05:00

I was thinking about the different kinds of technical diversity as I was driving to work this morning. On the one hand, there is planned technical diversity, which is when we intentionally use multiple technologies that exist in roughly the same sphere. Having some scripts written in Perl and others in Python would be an example. Either could, theoretically, supplant the other, but it is probable that they are suited to different tasks. Maybe Perl is a better fit for some textual parsing than Python. Sure, it could be done in either, but maybe Perl makes the work lighter (for someone).

Then there is the mirror opposite of planned technical diversity, which would be incidental technical diversity. I find that this most especially happens due to good old lava flow. We wrote in classic ASP before it was classic, then did new projects in ASP.NET webforms and finally moved over to ASP.NET MVC, but didn’t refactor or replatform the older code. It just lived on happily. The result being that we have a form of technical diversity that no one ever quite decided to take on.

The lava flow scenario is seldom good as most of the layers are in the process of becoming obsolete. But there is, I think, some value in planned technical diversity. There is a balance involved, as I’ve mentioned before. As before, I don’t know that there is a lot to mention with respect to risk. It has been amply said and generally applies to the most degenerate of situations.

One advantage is that, by maintaining an advance guard, we never find ourselves suddenly desperately behind the times. After all, our code bases don’t magically go out of date one day. They rust one day at a time. Expecting to stay current without continuous change is not reasonable.

Talent recruitment is another big thing. The best developers want to work with the best technology and want to to try the newest at the very least. It may not be possible to make the core product more glamorous, but it is possible to ensure that there is ample room for developer skill to work.

The last advantage I can think of is that technical diversity is itself a form of risk management. That is probably an ironic statement, given that risk avoidance is often one of the key arguments for restricting the toolchain available to an organization. What is interesting is that obsoleted tooling must be either maintained internally or replaced, regardless of whether or not it is open source. The difficult thing is that we can never really be sure which selections will turn out to be good ones, in which cases or for how long. Moreover, we can never be certain where we will run into unexpected security holes. By having investments in multiple technical stacks, we are protected against sudden dramatic issues with any single one. We are less likely to find that we have to apply emergency patches to everything or suddenly replatform the entire system.

The Rationality of Technical Debt

2019-04-17T00:00:00-05:00

Technical debt is a common worry amongst development teams. A long method, a near-duplicate web service, an old bit of tech stack. Our collective experience tells us that technical debt is bad, something to be avoided. Clean Code tells us how to avoid it and Joel Spolsky tells us never to rewrite because of it.

The whole of our collective experience drives us towards a bit of a dichotomy, a line in the sand that divides all parties into two groups. There are the intrepid software developers who see all technical debt as an intrinsic evil to be eradicated and avoided at all costs. The more business-oriented parties see efforts to remove technical debt as a sort of unnecessary geek gold plating that distracts from delivering on more important tasks.

One speaker I remember hearing proposed to bridge the gap by looking at technical debt as a form of risk to be managed. The rationale was that debt is not regarded as intrinsically bad in the business world. In fact, it is a necessity and excess liquid assets are even considered bad for the overall financial health of a company. If, however, we re-frame technical debt as risk the picture becomes clearer. There are risks, to be sure. Risk that support will falter, risk that security will be breached, risk that code will not be extensible in ways that are found to be desirable and so on.

Discussing the risk associated with technical debt is a good thing. The severity of risk is a strong factor in the importance of resolving any form of technical debt. I think a blanket relabeling of technical debt as technical risk would be doing ourselves a disservice.

A blanket relabeling would only be kicking the can down the road for a few years. At some point the message backing technical risk would become stale as the stated risks never seem to quite materialize. Then there is the fact that it would be almost laughable to refer to some of these things as a risk. How much of a risk is a method that is just a little too long?

I find the concept of technical debt is useful because debt is a form of risk, even in the financial world. The key, I think, is to place our handling of technical debt on a rational basis, almost like a balance sheet of some kind. If we can minimize the amount of emotion from the equation, we can have a much better conversation about how to deal with the debt on our code base.

At the end of the day, not all technical debt is created equal any more than all financial debt. It comes down to a cost/benefit analysis. For example, let us say that we are faced with putting some hacks into a product in order to make a deadline. The software developer would recoil a bit. Mar the code to make an arbitrary date? Irresponsible. Poor craftsmanship. An efficiency minded individual sees double work, first now and then later - and recoils as well.

Financial debt is (virtually) never interest free, so it costs more to pay for something through debt than if it were all paid in cash upfront. Nonetheless, it sometimes does make sense to take on that overall spend to have something sooner. Done right, this is due to opportunity cost. The extra effort paid to settle the debt amounts to less over all than the opportunity that would be lost if we had to wait. Software development is much the same. It might well make sense to take on the technical debt if, by doing so, we net an amount of opportunity (otherwise to be lost) that exceeds the full cost of effort.

In the example of trying to make a date we would need to ask whether making the date generates enough opportunity to be worth the effort of removing the hacks. This approach assumes, of course, that the payment of technical debt is non-optional. That payment is mandatory is what makes financial stewards weigh debt in a non-flippant fashion. It seems like there is an opportunity to mix the payment of technical debt into agile planning, ideally by making payments - that is, dedicating a portion of each sprint’s story points to resolving technical debt.

It also relies on the ability to quantify our technical debt which is something I don’t think we have a great handle on, as an industry. I think, if we can make all this happen - quantifying our debt and associated risk, making payments on our debt and discussing a “balance” with our stakeholders - we can make decisions about technical debt that are in the long-term best interests of all.

Change Avoidance-Driven Design

2019-04-10T00:00:00-05:00

Change Avoidance-Driven Design (or CADD, for short) is one of those things you don’t learn about in school. It has no place in Computer Science, little place in Computer Information Systems and none in the other STEM disciplines. I suppose one of those rare software engineering degrees might talk about it, but I have my doubts.

CADD is what happens when the desire to avoid changing certain pieces of a software ecosystem exercises a disproportionate level of influence on the approach taken to fix a bug or add a feature. Anyone who has worked in software for a couple of years will recognize this phenomenon almost immediately. In terms of recognizing CADD, it is almost easier to spot it by way of absence of changes in key areas rather than the presence of them.

Astronomy gives us a pretty good idea of how this looks in another discipline with the study of exoplanets¹. All of our telescopes are based on gathering electromagnetic emissions. Whether it we are talking about light rays, x-rays or something else, it all involves some form of radiation being caught by our instruments and analyzed. Any known planetoid would typically give off little by way of electromagnetic radiation being far outshone by other celestial bodies.

One of the more common methods of detection is to look for signs of a star wobbling on its axis for reasons not otherwise explicable. It is looking for something unseen, almost invisible exerting forces on other parts of the system. CADD is detected in much the same way.

Imagine you have several interacting systems that look something like the figure below.

Then let us imagine that we are going to add a feature by changing the systems indicated in the next diagram.

Isn’t it suspicious that several spokes on a wheel are changing but not the hub? That is the most generalized heuristic for detecting CADD at work.

The other thing I have noticed with regards to most instances of CADD is that they are almost always motivated by fear - fear being, of course, the most human thing about software design. The source of fear varies, of course. Sometimes it is fear of an unstable codebase with the propensity to break at the slightest provocation. Sometimes the fear is political in nature, in the form of distrust regarding a team or process. Sometimes it is the fear of a particular technology, either for its age or for its poor fit to the problem.

“I must not fear. Fear is the mind-killer. Fear is the little-death that brings total obliteration. I will face my fear. I will permit it to pass over me and through me. And when it has gone past I will turn the inner eye to see its path. Where the fear has gone there will be nothing. Only I will remain.”

– Frank Herbert, Dune

A paradox follows naturally from this state of affairs. Fear is seldom entirely without warrant. Acrophobia may not be irrational, but a fall from a height can kill you. Ophidiophobia may not be irrational, but people have died from snake bites. CADD works the same way. The codebase may be poor, the process may be painful, the team may be difficult, but, long term, good seldom comes from designing around a problem in perpetuity. There is always a reckoning.

So what do we do about it? Proceeding with caution is only rational, but we cannot do anything to make things better if we all tip-toe around a problem without even acknowledging it. The solution to an unknown technology is to learn, the solution to a poor codebase is refactoring and the solution to missed bugs is testing (automated testing being preferable). The commonality is that doing nothing solves nothing.

The hardest part is, as always, human and not technical. Convincing ourselves and then others to tackle hard problems and take the long view is hard. It is hard because it runs contrary to ease and relief in the short run. We are almost hardwired to maximize short-term gains, even at the expense of larger long-term ones. Every major methodology is about making short-term sacrifices for long-term gains. It is easier to write messy code - until we have to read older bits of code. It is easier to skip automated testing - until we are hit by a regression bug. The list goes on.

Balance, as always, is key. We cannot fix everything at once, or even everything at all, but we can apply the boy scout rule at the macroscopic level as well as the microscopic level of code.

This applies to other aspects of astronomy as well, but I like thinking about exoplanets. ↩

Halloweening

2019-04-03T00:00:00-05:00

Halloweening is that process that happens near the beginning of a non-trivial project or initiative when you know you will be doing work and have the elevator pitch for what the work is, but the details are either vague or in flux. For me, this collection of general starting points kicks off a period where I go door-to-door with stakeholders and colleagues, ring the doorbell and say “trick-or-treat.” One person gives me a spreadsheet, another gives me a collection of Visios or some emails and so on.

After I finish going door-to-door, I take my proverbial bag of goodies back to my desk and start sifting through it all, looking for the good bits. Slowly but surely, a picture of the project goals and probable implementation paths starts to coalesce, which enables me to go out and start filling in the blanks. “What about this feature?” “How would we accomplish that?” “What about the legacy system?” “How does this tie into other things we are trying to do?”, etc. There are always blanks, but knowing where the dragons are let’s us fill them in.

I have always found myself doing a bit of halloweening to start a project. No requirements document, email or diagram has ever completely obviated the need to ask around and there are almost always multiple tales to hear and many viewpoints to reconcile. I must say that there is a degree to which I enjoy it. It is like solving a murder mystery where we are finding something to be created rather than something that has been destroyed.

What are the keys to good halloweening? How do we go about getting the good stuff? I’ve usually found the first step is to know which houses to go to. Sadly, there is a degree to which this is mostly a matter of having enough knowledge of the organization, enough of a mental rolodex to know who to speak to. When in a situation where few contacts are known, the whole thing becomes a matter of discovery. I usually start with what I know and see where asking questions leads me.

The most important thing along the way is critical listening. If treated as a passive exchange of information, halloweening will end abruptly. Without the “critical” part in critical listening, questions cannot be asked and huge segments of canvasable territory will be missed.

The one warning to add is that it is important to be careful how much solutioning or decision making goes on. I try to treat the process as information gathering and I continue until my efforts are redirected to some other bit of work or until I stop hearing new information or getting new contacts.

There is a time and place for lobbying, of course, but without a solid working knowledge of what is being asked and the context into which the solution must be placed (and there is always a context), we really do not have a good notion as to what it is for which we should lobby. Ultimately, that is what halloweening is all about - putting oneself into a good position to create proposals, designs or presentations for future work.

Preface

2019-03-27T22:01:00-05:00

Welcome to Reality Denied! My name is Michael and this is my blog. I will begin publishing here weekly on Wednesdays. The initial focus will be on the software engineering and architecture topics on my mind. Hopefully, I will get around to branching out into other topics of interest.

The name of this blog comes from a quotation I once heard:

“Reality denied comes back to haunt.” - Philip K. Dick.

In a world beset by illusion and error, the goal is to see reality as it is, unvarnished rather than denying it and being haunted.

Reality Denied is a blog relaunch, of sorts. I had run a blog entitled Mad Computer Scientist that fell out of publication. I may import those entries here, but at the moment I am inclined to leave them as a read-only archive on https://mad-computer-scientist.net As G. K. Chesterton noted when publishing the second edition of The Wild Knight: “I leave these verses as they stand, although they contain innumerable examples of what I now see to be errors of opinion…there are verses I cannot take so seriously as to alter them. The man who wrote them was honest; and he had the same basic views as myself. Besides, nobody need read the book: I certainly beg to be excused.”

Since my last period of active blogging, I have spent less time as a primary contributor and more as a developer, architect and tech lead. This perspective is laced with its own pitfalls and errors, which I hope to write about here.

That will about do it for now. I look forward to seeing you for our first real essay next week.