Recent Posts (page 12 / 65)

Lint Filters And Testing

I don’t know about the lint filter on your dryer, but our current dryer, and every dryer I’ve used before this, had a message on or near the lint filter something like this.

That’s pretty good advice. Sure, you should clean the filter after you use it. It’s polite and you want to be helpful to the next person who uses the dryer, but that doesn’t always happen. As a user of the washer and dryer, it’s your responsibility to make sure that they are ready for your use. That means enough soap, softener (if you use it), bleach (if you want), and cleaning the lint filter.

It’s the same way with software. You should always endeavor to leave things the way you found them. Return unused resources. Clean up any temporary files. Reset shared state. In short, you want to eliminate any unintended side effects and make your system as idempotent as possible. You don’t want the current run to be unduly influenced by the previous run. The thing is, no matter how hard you try, you can’t be sure the code you have at the end runs successfully to completion.

Which means, before you do something, you need to make sure things are set up the way you need them to be. Especially if it’s a repetitive task. Like a unit or TDD test. You run them all the time. Potentially multiple times an hour. And sometimes they fail in the middle. So they need to be idempotent and side-effect free.

There’s a name for this pattern. It’s the Arrange-Act-Assert (AAA) pattern. Do all your setup. Everything from ensuring the (virtual) file system is in the right state to setting up the environment to building and seeding a database. Then make the ONE call that does the thing you’re testing. Finally, do as many asserts as you need to ensure that things went the way you expected.

The AAA pattern is that simple. Arrange things how they should be. Act on the system. Assert everything came out as expected. Like everything else though, in practice there are nuances and complexities. In many cases there’s a part of Arrange that you want to run once before any test, but not before every test. You might need to assert that the Arrange step actually arranged things correctly. You’ll find that a lot of the Arrange code should be re-used. You probably want to clean up after the Assert. And there might be a cleanup that runs after all tests are done.

Then there are the efficiency temptations. If you’re doing a CRUD test you’ll probably be tempted to do it in one test. After all, the Arrange for Read, Update, and Delete is Create, so why do it separately? It’s faster and less code to do it in one test right? Probably not. It might be faster on initial write, but over time, as the code changes, that unnatural coupling is going to slow you down. So don’t do it. Remember, Act is doing the one call that you’re going to test. If you have multiple Acts in your test you should split it up into multiple tests.

And don’t forget to clean the dryer lint filter before each load.

Measuring and Managing

You’ve probably heard the quote from W. Edwards Deming that

if you can’t measure it, you can’t manage it

Which is an accurate quote. It comes right out of The New Economics. And on the surface, it makes sense. Whether you call it OODA, Plan-Do-Check-Act, or just a feedback loop, how can you control (manage) something if you don’t know what’s going on? And the more accurately you know, the better you can control it. That’s just a basic feedback system.

The thing is, that’s just part of the story. Or really, part of the quote, which is hinted at by that leading lower case i. The full quotation is actually

It is wrong to suppose that if you can’t measure it, you can’t manage it – a costly myth.

Think about the difference between those two quotes. The first is Taylorism. Scientific management at its most basic and most rigid. Measure everything. Then use those measurements to force results. And if you can’t measure it, figure out how or ignore it.

The second is the complete opposite. It’s about being able to manage the situation based on what it is, qualitatively. It’s about knowing where you want to get to and working towards it. Even if you don’t know where you are. It’s about dealing with ambiguity and making progress from a place of ambiguity. It’s about working with the situation we have, not the situation we wish we had.

That doesn’t mean you can’t or shouldn’t use accurate measurements when you have them. Far from it. It’s almost always better when have data to guide you. The more accurate your feedback signal the better you can craft your response. And you should. You should, whenever possible, measure things. Collect metrics from your apps, libraries, and services. You should monitor those metrics and respond to changes. Ideally you measure them well enough to use them not just as indicators of problems, but as predictors of problems so you can respond to them before the problem starts.

But you should also recognize that you need to manage things even without those metrics. It might be because you don’t know how to measure something, or because measuring it would take too much time/effort/resources that would be better spend on something else. For example, you might not be able to tell how much better option A or option B will be, before or after trying them. You might just have a feel for it. But you still have to make a choice. You have to manage the situation. And if anyone tells you Deming says you can’t, tell them The Rest Of The Story.

Software Development Is A Social Activity

I’ve had a bunch of discussions lately around the nature of software development. Silos. Boundaries. Contexts. Cognitive load. Team Topologies. And how things flow and work together. Wheels withing wheels. Loops withing loops. Patterns within patterns.

Those discussions were all around how teams can and should work together. Where does one team’s responsibility stop and another’s begin. What’s the difference between a customer and a partner? How does value flow through the system? Platforms and Programs, Products, or Feature factories. The common thread in all of these discussions is that the relationships between the teams are more important than the code. That software development is a social endeavor.

Despite the myth of the lone wolf developer, for all but the tiniest projects/products on all but the tiniest embedded devices, you can’t do it alone. We build things with others. We build things for others. We don’t do our work, and our work does not exist in a vacuum.

On the other hand, no-one can know the details of everything. No one person can have enough information to make all the decisions needed. The cognitive load of that would be too high. No one can be in the right place to make all those decisions. Physics and time keep us from being in multiple places at the same time. So where does that leave us?

It leaves us with process and methodology. We come up with boundaries. Domain driven design. Bounded contexts. Discrete APIs. We come up with contracts and SLAs. Things that let us share knowledge and compartmentalize responsibility. Things that let us manage the complexity. Keep the cognitive load manageable. That let us focus on the things close to us and not worry about the things further away.

Or at least we aspire to have those things. But, honestly, we don’t. Instead, we have approximations. Leaky approximations. We have APIs and interfaces and microservices, which mostly let us not worry about the details. Except for the ones we do need to know.

Which means we’re back to people. And how they interact. People who need to talk to each other. Need to work with each other. And talk across all those leaky barriers. So they can make decisions across those leaky barriers. And use the fact that the barriers are leaky to help each other across those leaky barriers. And at the same time make the barriers less leaky.

As I write this I’m sitting on an airplane watching The Matrix: Resurrections. Talk about leaky barriers. There are the (semi) obvious barriers between the Matrix and the “real” world. There are the barriers between the world inside the (semi-real) Matrix and the Matrix computer game which Thomas Anderson has written. There’s the barrier between incarnations of the (semi) real Matrix. And that’s all inside the universe the movie takes place in

On top of that there are the barriers between the different Matrix movies. And The Animatrix series. And the changes the writers/directors have gone through. It’s almost like the directors and characters in the movie know that there’s an audience watching.

The leakiest barrier of them all is the audience. The audience knows many things about the in-movie universe that the people in the universe don’t. But there’s no guarantee that they’re not actually in a (the?) Matrix. After all, how would you know? Which is about as meta as it gets.

The thing is, what makes the caper in The Matrix work is the same thing that makes software work. The connections between groups. Within and across the leaky barriers. The understanding. The shared goals. The trust.

Because in the end, software development is a social activity. The choice is yours.

Where do defects come from?

For those that know me, it’s no secret that while I like a lot of Uncle Bob’s specific advice (clean code, unit tests, I have some problems with his overall approach. Consider his response to the question “Where do defects come from?”.

According to him, the cause is:

And the obvious solution is

It’s true that as software engineers we need to do a better job, have more discipline, and not make excuses for those that don’t. Raising the bar on how we do our jobs is vitally important to eliminating defects.

But it’s not enough. You can always find someone who typed the line of code and blame them for the problem. There’s even a git command, blame to do just that. But it’s kind of disingenuous to stop there.

I’ve been doing this a long time. In all my years as a software engineer, I’ve never run into a co-worker who didn’t care. Some had more information than others, and some had different experience and viewpoints that let them see things others missed. But no-one thought sloppy short-cuts were OK to take or that it was OK if someone else took one.

I’m much more partial to Hillel Wayne’s approach to thing. Not just in this case, but in many others. He takes a much more nuanced approach. He avoids the Tyranny of Or Yes, someone typed that line, but the defect has a deeper cause than that. Why was that line allowed to be typed? Could we have added guardrails to at least prevent it from getting into user’s hands?

It’s because for all but the simplest bits of software, running in all but the simplest environments, it’s not just one developer, or even one team of developers that wrote the code. The code uses libraries and OS functionality from somewhere else. Someone else built the environment. The hardware the code runs on and the network it’s connected to are managed by someone else. It’s part of much bigger, interconnected, and interdependent system. To say that one person is responsible for an error in such a system isn’t accurate.

Which is not to absolve developers of responsibility for defects. They need to have discipline and be professional. There is no excuse for sloppy work. But it’s not enough. We also need to ensure that we have, and use, all of the tools at our disposal to not just find defect, but even better, keep them from happening in the first place. Because the goal is to make sure the defects don’t reach the customer, not figure out who to blame for them.

A little housekeeping

It turns out, unsurprisingly, that having 500+ blog posts in a single directory isn’t a great way to run things. To that end, I’m moving a bunch of stuff around. To you the user there isn’t much change. The new links are of the form /posts/<year>/<month>/<day> instead of /posts/<year>-<month>-<day>. If you’re following a link with the old format it should still work, but if it doesn’t, you’ll get a message saying it’s unavailable and a link to the new format.

I’m pretty sure I’ve fixed all of the internal links, but there may be a few I’ve missed. If I’ve missed something just shoot me a quick note and I’ll fix it. While you’re waiting you can do the manual translation. For me, though it makes things much easier under the covers. For anyone who’s having problems finding things, I appologize. This new system should work for the next few years at least :)

thanx

leonr

Elevator Pitch

I’ve talked about vision and mission statements before. I’ve talked about strategy and charters too. Visions, charters, and strategies are big things. They can take a page or more to write down, a long time to describe, and even longer to really understand. Mission statements are often just as bug.

But there’s one kind of mission statement that isn’t big. It doesn’t take that long to explain or understand. When you hear it, you know exactly what the mission is, and if you are part of that mission, you also know exactly what your role in achieving that mission is. That kind of mission statement has another name. The Elevator Pitch.

The elevator pitch comes to us from Hollywood. The story goes that if you had a project you wanted to get made and didn’t have a well-known name or portfolio and wanted to get a chance, you’d somehow manage to get yourself in an elevator with someone who did have the power, budget, or connections needed to get it made. Then, while you were in the elevator with that person, you’d make your pitch.

The elevator was a great place to make the pitch because there were no distractions and the person couldn’t leave. On the other hand, elevator rides are short. A minute of two at best. You didn’t have a lot of time to make your pitch. This one simple constraint drives the elevator pitch more than any other.

Which means your elevator pitch needs to meet a few requirements. First, of course, it needs to be short. It also needs to be clear and complete. That’s hard enough to do. But it’s not enough for an elevator pitch. It also has to be catchy. It has to grab the listener and make them want to know more. Make them want to get involved. Make them want to help you get your project made.

Making a company’s mission state also be an elevator pitch add yet one more level of difficulty. Because there are two very distinct types of people who you need to craft your elevator pitch for. The first is the people outside of the company. The customers, users, critics, shareholders, and investors. Those people need to know what you’re doing, what is good for them, and what you consider success.

The second is the people inside the company. They often have a lot of overlap with the first group, so all of those things are important to them, but the elevator pitch also needs to tell them what they need to know so they can do their part in executing the mission. And by the way, while you tell those internal folk what they need to know, you don’t want to scare off the people outside.

It’s a lot of work to craft such an elevator pitch. Lots of things that need to be included. Lots of constraints that you need to honor. But, done right, a mission statement that is also a good elevator pitch can drive a company (or team, or even an individual) far beyond where they might have gotten without it.

Consider Microsoft’s early mission statement, “A computer on every desktop, (running Microsoft software)”, or Uber’s early one, “Transportation as reliable as running water”. Both are very short. They are simple to understand. You know what success looks like. From outside the company, you know what the company is doing and how you’ll be better off after it comes to pass. From inside the company, you can look at every decision you make while doing your job and make the choice that drives the mission.

So what’s your company’s mission statement/elevator pitch? Do you have a pitch or just a mission statement? What about your team? Or yourself? If there isn’t one, should there be? What can you do to make it happen?

Why We Test

We test to find bugs, or at least make sure there aren’t any, right? Wrong. Or at least it’s not just about finding bugs. Finding/eliminating bugs is one of the specific things we do as part of testing, but that’s not the goal. It’s not about lines or branches covered. It’s not about having tests pass or dogfooding. All of those are things we should do along the way, but they’re not the reason we test.

I think Dan North said it really well.

The purpose of testing is to increase confidence for stakeholders through evidence.

That’s why the things we do, fallbacks, guardrails, formal analysis, input validations, code reviews, unit tests, code/branch coverage, integration tests, dogfooding, etc., are important. These things give us concrete numbers that describe things we know about the code and the system. They are how we provide the evidence needed.

That data lets us show how we have reduced risk in different ways. They’re not foolproof though. We don’t test all possible combinations or sequences of inputs. Even tools like TLA+ can’t guarantee correctness. All we can do, especially in a complex system is increase our confidence (by reducing risk). Risk analysis is a complex topic itself for another time, but for simplicity, risk and confidence are inversely related. Reducing risk increases confidence.

Just understanding that isn’t enough for the people designing/implementing/running the tests. You have to understand who the stakeholders are and what’s important to them. Stakeholders are everyone impacted by you building the thing under test. Not just the users, direct and indirect, but you as the builder, your team, your manager, and your company. Each of them have different views, different requirements, and different levels of acceptable risk. Depending on who and what you’re doing you could be in many different stakeholder groups. You may also be completely separated from one or more of them. You still need to understand them and what is risky to them.

Because at the end of the day, we’re building things to add value for some group of people. We test to get the confidence that what we’re building will do what it’s supposed to an acceptable level for those people. That’s why we test.

Careers Pt 3 - Visualizing Progressions

In part 1 I talked about how your “level” or title was just a way to describe the scope of influence you had. Just a measure of how much your work, and how you worked, impacted others. Part 2 explained more about what I meant by “scope”. What the parts of scope were and how scope could grow.

Being able to describe how that works is crucial to managing your career. Just as important is being able to describe it to others and to visualize it. That lets you discuss it with others. Because while you’re responsible for your own career, you aren’t alone in a vacuum. Being able to visualize where you are in your career and your progression through your career lets you understand where you think your gaps and opportunities are and compare them to what those around you think.

To that end, I’ve been playing around with a bunch of different visualization formats. I wanted to show 3 different values for each of 6 different areas in one place. I tried text, line graphs and bar graphs, but none of them really captured what I wanted. Eventually I settled on a radar plot with an overlay and accompanying text.

The radar plot breaks the circle down into the 6 “competency” areas. The different rings represent the scope of influence for each level (self, sub-team, team, project, group, or division). Then, for each section of the circle the colored arc represents what you (or whomever is creating the plot) considers your scope of influence. Finally, you can overlay a circle on the plot with your current level. The text area gives you a place to describe significant information/events that led you to pick that particular scope of influence for that area. I’ve put together a progression of radar plots that lay out expectations in each area at each scope.

Where this gets really interesting and useful is when you use it to manage your career. Pencil in where you are on the radar plot. Then get your manager to do the same. Once you have both, compare them to expectations. If both you and your manager agree you’re exceeding expectations in all areas then you have an easy discussion about next steps. If you and your manager agree and there’s a gap between where you are and expectations then the conversation is still pretty easy. Identify the gaps and discuss what you can do more/less of or new areas to move into to close that gap.

If you and your manger disagree on where you are then you have a harder conversation, but it’s the one that’s probably most important. Making sure the two of you are on the same page is the single most important thing to managing your career. Those gaps indicate places where the two of you aren’t on the same page, so that’s what you need to be talking about. It might be expectations. It might be visibility. It might just be lack of awareness. Whatever it is, now that you know about it you can (and should) do something about it.

Finally, one last things you can do with these visualizations is look at them over time. I put one together for my career. It’s a lot of things, but one thing it’s not is smooth. And that makes sense. Over time, particularly around job changes, you perform at different levels. Don’t be surprised when it happens. In fact expect it. Take the time to look around, identify the gaps, then close them and move on. That’s owning your career.

If you’re really interested, you can see my history (and a couple of “generic” career progressions I’m putting together for discussion purposes) in the Eng Stories area.

Action vs. Reaction

Bias for Action is one of Amazon’s Leadership Principles. Bias for Reaction is not. They sound very similar. And from the outside they look very similar. But from the inside they’re very different.

Bias for action is about making decisions. It’s about being thoughtful and using the information you have at hand to make a good decision. It’s about understanding the options and then deciding amongst them.

Bias for reaction, on the other hand, is about doing something, anything, instead of taking the time to think and make a decision. It’s about motion. It’s about not appearing idle. It’s about looking like you’re invested in the situation.

Bias for Action is a good thing. Bias for Reaction, not so much. The key is to understand that difference and then act on it.

As part of Amazon’s leadership principles, Bias for Action is described as

Speed matters in business. Many decisions and actions are reversible and do not need extensive study. We value calculated risk taking.

Or, in other words, when faced with an reversible decision, use the information you have and make the best decision you can. Then move forward. If you need to change it later, change it then. Don’t agonize over the decision and don’t let yourself end up with “Analysis Paralysis”.

At Amazon the key to making decisions at speed is understanding whether the decision you’re making is reversible or not. Whether it’s a one-way door or a two-way door.

A two-way door is decision that is simple to make and if you choose to, simple to unmake. Realize you’ve stepped through a door into the wrong conference room? Step back through the door and find the right room. The cost of getting through the door either way is about the same and pretty cheap.

A one-way door is like the emergency exit at the bottom of the staircase. The one that says “No Re-entry To Building” and when you get outside there’s no door handle. If that door closes you can’t just step back in. You have to expend a lot more energy (pounding on the door and hoping someone responds or walking around to the main entrance) to get back in.

Bias for action means first understanding if you’re about to go through a one-way or two-way door. Before you can make a decision on what to do, you have to decide what kind of decision you’re making. Then you make your decision. With the appropriate amount of research and study.

That’s Bias for Action. Not doing that is Bias for Reaction. And that can get you in a lot of trouble.

Story Splitting

The typical user story starts something like

As a <persona>, I should be able to <task to complete>

That’s a decent format, or at least it’s a minimum bar. Without identifying the kind of user and the task to complete it’s really hard to compare tasks to identify which has the highest value. However, it is by no means a guarantee.

There are 2 really common reasons that this template doesn’t guarantee that you end up with a quality user story that you can implement. The first is that there’s no mechanism to ensure that the task the user is trying to complete is actually a task that adds business value and not just an activity along the way to completing a task that adds value.

The canonical example of this is the login user story. You know, the one that reads something like

As a return website customer I should be able to login to the website.

That story hits all of the requirements of a user story. The customer is clear. The task is clear. Acceptance criteria, while not explicitly listed, is clear. Even with all that, it’s not a good user story. It’s not a good user story because the task, logging in, doesn’t add any value. It’s an activity that needs to be done, so by all means, do it. But if all you did was add the ability to log in to the site then you wouldn’t be adding value. You’d also be making your customer’s life worse. They would need to jump through some hoops, but things wouldn’t be any better.

A better user story, with a task that adds value, would be something like

As a return website customer I should be able to order the contents of my shopping cart using my securely stored personal information.

Do you need to be able to log in? Maybe. You need to access securely stored information. Logging in is one way to do that. But there are other mechanisms for authentication. The user story is not the place to specify the mechanism. The team should figure out the mechanism by looking at the situation. And once they have the mechanism determined/implemented, they can then use it to ensure that secure personal information is used. The customer doesn’t need to enter information every time and you don’t need to send the info over the wire making things even more secure. And that adds user value. When the story is done the user is measurably happier.

The other common reason, and the one I see more often, goes the other way. The story is too broad.

As a return website customer I should be able to buy something

That is certainly something a customer wants to do, and doing it adds value, but where does the story start and end? That story covers just about every e-commerce site ever made. To really be useful and completable in a reasonable amount of time it needs to be split up into many more much smaller stories or scoped down to what the story really means. That story is probably a conflation of at least stories for browsing, adding items to a cart, setting delivery address, and making payment. I needs to be split up into those stories. The challenge there is to not split the story up so far that it turns into a task list (see above).

Right-sizing stories is the key to making useful user stories. Making them big enough to actually add value, but not so big that they can never be completed. Tim Ottinger has a good list of resources for splitting stories.