Recent Posts (page 6 / 70)

You ARE Allowed To Think Before You Type

I’m a big proponent of agile (lower case a) development practices and Test Driven Development (TDD) in particular. In my experience it conforms to the reality of changing understanding and moving requirements much better than BDUF. Like many things, there’s a spectrum ranging from BDUF to “Start typing and see what you come up with”. And in some specific scenarios, either one of those might be the right choice. But for the vast majority of us, in the vast majority of cases, the best choice is somewhere in the middle.

Unfortunately, the best sound bites are at the extremes. Things are so clear there. There’s no nuance or reality to get in your way. You end up with everything from “The product and architecture teams have specified every function/message/API call, so just go implement this skeleton.” to “Build me a website that tracks all of my activity. I’ll be back on Friday for a demo.” It’s easy to look at either of those and say that there’s no way that they’ll work. And they don’t.

So here’s another sound bite to get you thinking.

Continuous design is an interesting thing; it can be continuously coming up with a design (with some reversals) or it could be continuously testing pre-thought design ideas by implementing them and assessing.

Both are valid. You are allowed to think before typing.

     Tim Ottinger

I say nay, not just allowed. I would say you are required to think before you type.

It’s the messy middle, the land of “It Depends” where software engineering lives. The place where we need to understand not just what we’re doing, but why. To choose what to do for a valid reason, and just as importantly, choose what not to do. The way to do that is to think. Think about what your goals are. Think about what your constraints are. Think about the path, not just from 0 to 1, but from 1 to 10 as well.’

I’ve talked about only designing until you start speculating. But it goes even deeper than that. Until you’re done, you’re speculating. Even then, you might be wrong. You can (and should) design for the known knowns. You should have a approach for known unknows. But by definition, you don’t know the unknown unknowns, so you can’t design for them.

You might not be able to design for them, but you can keep from painting yourself into a corner. Especially if you’re using TDD to guide you, you have to think first. You can’t write the initial list of failing tests, let along the tests themselves, unless you have some idea of how things are going to work. How the events and data, the information is going to flow. How it’s going to be transformed.

To break things down into domains, you have to have some understanding of the situation. And not just the happiest path. You have to think about the edges. The failure cases. The places and ways things can go wrong. It’s only after you’ve thought about those things that you can create your domains and use tests to guide your development.

And all of that is speculation. You don’t know until you’ve tried.

So think. Then type. Then think some more. Then learn. Then design. And know that even those sound like separate things, they’re all happening somewhat concurrently. And that’s OK.

10 Commandments of Code Review

Programming is a social activity. We work with other people, not in a vacuum. We share code with other people. We share ownership of code with other people. We share responsibility for code with other people. The sharing goes the other way as well. Others share their use cases, their requirements, and their experiences. One of the places where all of that comes together is in a code review.

In some cases, such as pair or mob programming, code review is a synchronous, ongoing activity, but that’s not what I’m going to talk about now. For most us, code review is an asynchronous event. Someone changes some code, throws it over a wall for review, then waits, more or less patiently, for a response. Eventually some sort of agreement is reached, and the code gets merged into the codebase. I have a lot of issues with the whole “throw it over the wall” approach, which is another thing to talk about at a later time. Meanwhile, here are 10 important things to keep in mind when writing or reviewing a code review.

1. Thou shalt treat a code review request as an important task. Of course, you should give a thorough review when you give one, but there’s more to considering it important than that. It means declining quickly if you know you’re not going to be able to do the review. It means not putting it off for days. Different teams have different benchmarks, but 1 working day is a good rule of thumb.

2. Thou shalt create code reviews knowing that others will read them. As I said earlier, always review your code review before sharing it. Make sure it has what it needs for the reviewer. The right files. The right explanation of why the change is being made. A description of the change that someone who didn’t make the change can understand. A list of tests to validate the change.

3. Thou shalt not take comments personally. When reading comments on your review, remember, the comments are about the code, not you the author. Don’t get angry and ignore the comments. Take them seriously. Be willing to accept feedback and be willing to push back if you have a well thought out reasons. Nor shalt they make comments personal. Comment on the code, not the author.

4. Thou shalt keep your review to a single topic. A code review should be about a single logical change. If you find you need to keep using and in your description, consider splitting the code review into multiple reviews.

5. Thou shalt consider all feedback. Not just consider and ignore, but consider and respond. The response might be changing the code, it might be an explanation of why you’re not changing the code, or it might be agreement and a promise of a follow-on change.

6. Thou shalt say why. Whether it’s the code review description, a code review comment, or a reply to a comment, always explain yourself. It can be as simple as “I agree” if there’s no disagreement, but “No” is not acceptable, “No because …” can be.

7. Thou shalt not be absolutist. Writer or reviewer, be willing to compromise. Is good to have a strong opinion. It’s good to explain yourself. Like with everything else development, the right solution for a specific review depends on the context. Be willing to listen to the other people and work together to come up with a solution you all can more forward with. Again, remember that it’s OK to say there is more work to come, either right away or later when you know more about the situation.

8. Thou shalt not argue with the style guide. One thing I like about Go is that most of the style guide is built into the language and there aren’t any options. The writer and the review might not agree with it, but it is what it is, and we all go with it. For other languages you might have more choices, but the review is not the place to argue them. If you need to argue about the style guide, do it outside the review.

9. Thou shalt remember review feedback. The first time you receive some feedback it’s a learning experience. The second time you get the same feedback it’s helping you build a habit. If you get the same feedback a third or fourth time, stop for a minute and think about why. Understand where the feedback is coming from and incorporate the learning into your future reviews. If you’re not learning from your reviews, you’re being disrespectful to your reviewers.

10. Though shalt treat your review partners as you want to be treated. Just like that other golden rule, whether you’re the writer or reviewer, think about how your partner will feel. Think about how you would feel if you were on the other side of the equation. Then act the way you would want yourself to act.

Code reviews, regardless of which side you’re on, are there to help produce the most value you can. But they can be so much more. They can be teaching and learning tools. They can be vehicles for sharing. They can be a gift that you give to yourself and that teams give to themselves.

If you let them. So take advantage of your opportunities when you can.

Optionality

There are lots of reasons to have high internal software quality (ISQ). Minimizing WTFs/min is only one of them. One of the biggest reasons is not what ISQ does for you today, but what it will do for you tomorrow. The optionality it gives you for the future.

So what is optionality, and why should we care?

optionality (countable and uncountable, plural optionalities)

1. (finance, business) The value of additional optional investment opportunities available only after having made an initial investment.
       The short-term payoff for this is modest, but the optionality value is enormous.
2. Quality or state in which choice or discretion is allowed.
       Some offices do not follow the corporate procedure, due to a culture of optionality.

We care about optionality because software is all about change. In this case we care about both senses of the word. Sure, a particular release is a snapshot of a moment in time, and unchanging, but even in the days of shrink-wrapped software that you got off a shelf, there were often updates and patches, to say nothing of next year’s version. Now, with Software as a Service, Web execution, downloadable content, it’s not unusual to have multiple releases on any given day. So software changes, and optionality is important.

Some of you might be saying “But I write embedded code for an unconnected device. My code can’t be updated. I don’t care about change.” It’s true that once released that code can’t change. But right up until release the requirements can change, and they often do. So even in that case, writing software is about change.

Even more fundamentally, every character you add, remove, or change (there’s that word again) is a change to the software. The progression of a product, from idea, to design, to code, to release, is about change. Again, development, of any kind, including software, is about change.

Given that you know you’ll need to make changes, even if you can’t know what some of those changes are, giving yourself the optionality to go in whatever direction you need to go in is important. And that’s the biggest benefit of ISQ. Knowing that you can tackle the unknown unknowns that you know are coming with confidence.

ISQ is things like low coupling. That’s what lets you adjust the internals of one part of your code without having to worry about how it will impact other parts. As long as you don’t break your interface contract, you can do what you need to safely. Your unit tests, which are a part of high ISQ, let you know that you’re maintaining your contract.

ISQ is things like readability. I’ve talked about Coding for the Maintainer many times. Doing that is part of having high ISQ. If it’s easy to tell what’s happening, why choices were made, and more importantly, why other choices weren’t made, you have more options available to you. You can change your mind with more understanding, which leads to better decisions.

ISQ is things designing for test and using well written tests. If you have designed your components to be tested, you have lower coupling (see above) and you can test things without worrying about the testability of a dependency. It’s making sure your tests are tied to the outcomes of the things being tested, not the process of the thing being tested. It’s using fakes, mocks, stubs, and the real thing for dependencies at the right time¹. If you do those things, you can make changes with the confidence.

There are lots of other things that go into ISQ, but just doing those things isn’t the goal. And just having higher ISQ isn’t the goal. The goal is to give yourself more optionality. Higher ISQ is just one way to get that optionality. To have confidence that you’ve changed what you wanted to change, and just as importantly, that you haven’t changed anything you didn’t want to change.

Review Your Own Code Review

I’ve talked about code reviews before. There’s are things you should do when you review code, and there are things you shouldn’t do. Most of those things are about what to do when reviewing someone else’s code. The rest are about what goes into preparing a good code review.

I stand by those ideas. But there’s on important thing that goes into preparing a good code review that I haven’t mentioned in the past. That’s reviewing your own code reviews, before asking anyone else to look at them.

One of the biggest reasons is to know for sure exactly what is going into the review. In order to write a good title and summary, you need to know what you’re summarizing. You want to be clear about what’s included, and for that you need to know.

It gives you a chance to see how many “ands” you put into your summary. Very often you find that to do the thing you set out to do you need to make a bunch of other changes to make it possible. Since each review should do one thing, the self-review is a good time to catch that you should split the review up into multiple reviews. NB: Your reviewers will thank you.

Since you’re looking at the entire thing at once, are you being consistent? Are you being readable? Do things visually flow? Not just formatting, you have rules and formatters for that (don’t you?), but in structure and naming. Do you call something inventory in one place and stock in another? Make them the same. Did your method grow to 300+ lines? Break it up. Are you calling methods from hither and yon? Do you need to jump around/across files to follow what’s happening? Consider bringing things physically closer together to make reading/debugging easier.

Did you leave yourself a note to looks at something related later? I do that all the time since I don’t want to change contexts and track something down. I also often forget that I wanted to track that thing down, so seeing the note during the review gives me another oportunity to follow through.

Another thing you get from self-review is the chance to notice any debug helpers you left in the code. Things like extra print or log statements, parameter overrides, or changed defaults. Once you find them you’ve got an opportunity to change things. Should those prints be log messages? Should the logs be at a different level? Are you changing or adding a default that needs to be documented?

Speaking of documentation, this is also a good time to check and make sure that there is appropriate documentation for what you did, why you did it, and why you didn’t do something else. You’ve already done it once, but this is your chance to look at the changes in totality and make sure.

What about unit tests and/or code coverage. Do you have enough? Neither are guarantees, and you hopefully have automated systems that will check this for you, but being a good neighbor means the code under review is done. If you have folks do a review its better if you’re sure all the existing tests still pass, and any needed tests have been added. If not, you’re going to have tyo go back to your reviewer and ask them to review things all over again once you fix those problems. That is not the way to make friends.

What it comes down to, and what all these benefits add up to, is the chance to make sure your change is done and really ready for review before you send it on to others. Between context switches and the time taken to do the review, you’re about to cause multiple man hours of work across multiple people. It’s on you to do your homework first.

Demands ...

What if I told you that your time was limited? That the number of things you could get done in any given period was limited? You’d probably say “I know that.” And you do. You know you can’t do everything, and you know you can’t do everything at once. However, you’re not in control of what you need to do. Hopefully you’re involved in the decision, but while the how is often fully on the development team, the what and the why usually aren’t.

But what if I told you that you are in complete control of a big part of what you need to do? Broadly speaking, you can split what you need to do into two categories. The things you need to do to add value, and the things you need to do to because of things you did to yourself.

Adding customer value is pretty straightforward. A new feature. A new capability. Automating the manual. That’s the value demand. The demand on your time/capability where the result is customer value. And providing customer value is what we’re all here for.

The other category, things you need to do because of things you did to yourself, is the set of demands on your time that includes things like keeping the lights on, responding to customer issues, bug fixes, outage response, and other similar “customer service” demands.

That’s what Vanguard calls Failure Demand. They’re even more prescriptive about what Failure Demand is. To them:

It is demand caused by a failure to do something or do something right for the customer. Customers come back, making further demands, unnecessarily consuming the organization’s resources because the service they receive is ineffective.

Put that way, it’s simple. Everything is relative to the customer (internal or external). Add up the two things and that’s the total demand. The amount you do is constrained, so for a given amount of capacity, to maximize value demand met, you minimize failure demand met.

Sure, you could just not do the failure demand, and for a short time you can get away with it. But do it for too long and you lose customers because no matter how much value you think you’re adding, they aren’t getting enough value because of the failure demand they’re living with. A much more sustainable way of dealing with it is to minimize the amount of failure demand that your customers are generating. You do that by moving a little slower. By being more careful to finish what you’re doing. To not release those issues in the first place.

You can’t know everything up front, and you will learn things from releasing, but by paying attention to what you’re doing, by having sufficient testing, by making things resilient, by improving quality overall, you reduce failure demand.

Which naturally gives you more capacity to respond to value demand.

The Tao Of Pooh

I’ve always liked Winnie the Pooh. He may say he’s a bear of very little brain, but I think he’s got a lot of deep understanding that we could all benefit from.

While I’m reasonably sure Pooh was not an extreme programmer, that’s not a bad paraphrase of what extreme programming and the agile manifesto are getting at. Do the work and the work will show you what needs to be done. You do what you can do, and you find out how to do the next thing.

To know the way,
we go the way,
we do the way.

The way we do,
the things we do,
it’s all there in front of you.

But if you try too hard to see it,
you’ll only become confused.

I am me and you are you.
As you can see;
but when you do
the things that you can do,
you will find the way.

The way will follow you.

For example, I used to fight with my code sometimes. Or more accurately, I fought against it, trying to make it do what I wanted, not what it wanted. Then I realized I was wrong. And not just wrong to be fighting against my code, but wrong about code ownership and wrong about what I was fighting against.

Firstly, and long term, probably the more important, was that it wasn’t really my code. I might have written it, and I might have been the person that knew the most about it, but it wasn’t “mine”. Code has its own existence and its own purpose. The work I’m doing with the code is designed to get something done. To add value to the code, to the system. Not to make me more valuable by owning more code. It’s not about me, and while Imposter Syndrome is real, beating your head against some code is not the way to approach it.

Second, and the more tactical part, is that you can’t fight against code. You can’t make it do anything it doesn’t know how to do. You can use it different ways, and for different things. You can use it in ways that it was expected to be used, you can find new ways to use it in new situations, and you can use it in ways that are different and the opposite of how the original writers intended it to be used, but you (largely) can’t make it do something it doesn’t know how to do.

Instead, what you’re really fighting against is yourself. Your understanding (or lack of understanding) of what the code is doing and is supposed to do. How it works, and what its side effects are. The way to approach that is not through fighting or struggling, but through education. Reading documentation. Reading code. Exercising code to characterize how it actually responds (because documentation isn’t always correct). When you understand yourself and your biases, when you understand the code, its strengths, weaknesses, abilities, and constraints, you find that you’re working together, with the code to meet your goals, instead of against it. You find you’ll go farther and you’ll get there faster.

So like Pooh says, it’s all there for you to see. You just need to not try so hard. Let yourself see how things are and how they should be. And that will lead you to the way.

Primitive Obsession and Boolean Blindness

George Boole brought us Boolean algebra. There’s tremendous benefit in using it. Boolean algegra is one of the foundations of computer science and factors into a lot of what we do as developers. But sometimes, it can also blind you to a deeper truth.

I’ve talked about primitive obsession before. It’s where you use a base type to represent a specific domain type. Like storing a URI as a string, It works, and its faster at first, but it’s also very limiting. Instead of building an object that understands itself, you build the functionality to use the primitive type as if it were the domain type. It works, but future you is going to be unhappy.

Boolean blindness is a specific kind of primitive obsession. That’s where you use a Boolean value to store the value of something that is really more nuanced than that. There are two common ways this happens.

One is where things don’t map neatly to True/False. Instead, you have some possible list of values and some of them would be considered True and others would be considered False. This can happen a lot in state machines, like bug databases. You often want to know if a particular entry is open, active, or closed. That entry, however, can have many states than that. You could have a Boolean for every possible state and some complex logic that keeps them all updated, at the same time, but that’s brittle and error-prone. A better choice might be to have a enum for the possible states and a way to determine if a given state IsOpen or IsClosed.

The other case is where there is a very clear definition of True/False, but there’s more data you want to store. In my Wikipedia entry (if I had one), there would be a birth date, but no date of death. I could have two variables, a Boolean called isDead and a Date called diedOn. The second would only be meaningful if the first were true. That works, but again, that’s very brittle. You need to make sure that diedOn is only used when isDead is True, and that any change to diedOn changes isDead appropriately. A better choice here would be some kind of nullable or optional date, diedOn. If diedOn has a value then I’m dead and the value is when I died. If it doesn’t I’m still alive. It might be wrong, but it can’t be inconsistent.¹ It’s easy to imagine a much more complex class where isTrue is a complicated function of a bunch of internal state. Most languages won’t let you define the truthiness of a class, but you can imitate it by having a method on the class IsTrue() that handles that for you.

In other words, sometimes Boolean Blindness hides information by turning a multi-state thing into a two-state thing. In other cases you have the information and you just end up repeating yourself (and often getting out of sync). And sometimes that Boolean really is what you want. The trick is to actually make the choice knowingly, not by default or by mistake.

Deploying vs. Releasing

Today’s thought is courtesy of the inimitable @mipsytipsy (Charity Majors).

Deploys and releases are two different things:

DEPLOY – building, testing, and rolling out new code changes; hopefully small, incremental ones, very often

RELEASE – changing user experience in some meaningful way (not just minor bug fixes)

Sounds simple, no? In reality we confuse the two all the time. Or at least conflate them. Every deployment changes how things behave. And the only way to change it is to deploy again. This might not be a big deal if your change/build/validate/deploy cycle is on the order of minutes, but when it’s on the order of hours (or days or weeks) that’s a real problem. You become afraid to deploy, so the cycle time gets longer, more things end up in each deploy, and things get even longer.

It’s the exact opposite of a virtuous cycle. It’s a death spiral that ends up with huge deployment/releases that don’t do what you want, don’t let you respond to feedback, slow down the development cycle, and upset users. I’m pretty sure that’s not how we want things to go. I know I’d much rather be able to release a small change to my users and have them see a small change that I can iterate on. And undo if they don’t like it. Or it has some unintended side effect. Something I can be comfortable releasing now, whenever now is, knowing that if there’s a problem and quickly undo it.

That gives me confidence to try things. Things that I expect make things better for users, but I need more feedback on. Things that a focus group liked but might not be broadly applicable. Things that change internal data flow but have different operational characteristics than how things are now. Or any other change, really. The easier it is to go back through that two-way door, the more doors I can go through.

Of course, making that happen isn’t easy. You need a rock-solid build/validate/deploy system, which is not a simple thing to build. You need a robust system to distribute and use feature flags (or the equivalent). Also, a non-trivial solution.

You also need a way to clean up after yourself. You can’t leave everything behind a feature flag forever. If nothing else, the combinatorial explosion of possibilities will make it impossible to validate even a majority of the possible configurations. Some of them will be contradictory. Some will just break. The code gets too ugly and hard to understand. You end up with nested configs and then you can’t turn one thing on/off by itself, which defeats the purpose of doing this in the first place.

Now not every change should have deployment separated from release. It depends. Sometimes there are underlying changes that must happen at the same time as the code change. Sometimes the change is so pervasive that making it optional doesn’t make sense. But those kinds of things are much rarer than you think.

So instead of just assuming Deploy == Release, think about what it would take to make deployment and release two entirely separate actions.

Let It Flow

Like many things, I’ve talked about Flow and WIP before. The idea that what you want to optimize for is getting things done, not doing things. That’s a pretty subtle difference, but it’s an important one.

Or as it was said in Principle of Product Development Flow,

In product development, our problem is virtually never motionless engineers. It is almost always motionless work products.

– Donald Reinertsen

So much of how we work is designed to keep us busy. Blocked on waiting for someone else to do something? Start another task. Waiting for some tests to run? Start refactoring your code. Whatever you do, don’t just do nothing.

Now to be clear, I’m NOT recommending you sit around and do nothing if you can’t work directly on whatever it is you’re doing. That is not going to help.

But instead of doing nothing or starting the next task, maybe help the person you’re waiting for. They might get done sooner, which helps them get back to what they were supposed to be doing. Even if it makes things take a bit longer, the next time you’re in that situation you won’t need to bother them. You won’t be blocked, and they won’t be interrupted. Better for everyone.

Or another typical case. You need to run an integration test. It takes 20 minutes, so as soon as you start it, you go do something else. It takes you 15 minutes to context switch and get back up to speed. Just as you start getting somewhere, the test finishes. But you don’t notice because you’re busy. 10 minutes later you notice and go back to the first task. After another 15-minute context switch. You’re back to where you were before the test started. Think about it. You just spent 40+ minutes (2 context switches and a bit of time actually working) for 10 minutes of progress. Do that 3 or 4 times a day and you’ve wasted way more time than you’ve been productive.

Another quote from the book is

Since high capacity utilization simultaneously raises efficiency and increases delay cost, we need to look at the combined impact of these two factors. We can only do so if we express both factors in the same unit of measure, life-cycle profits. If we do this, we will always conclude that operating a product development process near full utilization is an economic disaster.

I know there are a lot of management buzzwords in there, and SAFe has picked up on this quote in particular, but that doesn’t mean it’s wrong. Like most things engineering, it’s a trade-off, and the answer always starts with “It depends …”. And with all trade-offs, the way to make it is to understand what you’re trading off against something else, and what your priorities are. It comes back to are you trying to optimize for doing things or for getting things done?

Here are some more interesting quotes from the book. There’s a lot to think about there.

K. I. S. S.

This is something I keep coming back to. Whether it’s talking about The Unix Way or the difference between complicated and complex, we seem to like complexity.

Developers are drawn to complexity like moths to a flame, often with the same outcome

– Neal Ford

It’s not surprising. It’s in the nature of the problems we’re trying to solve. We’re often dealing with large problems in real-world situations. People are involved, and people are complex. While they may be somewhat predictable in an aggregate sense, even Hari Seldon’s psychohistory didn’t (and couldn’t) predict the Mule. Or as Ian Malcom said, Life finds a way. Complexity is all around us, and we often feel like the only way to tame it is to build something even more complex.

But what it it’s not? What if the best way to deal with complexity is to make things simpler? To build things that are in and of themselves very simple. They do one thing and do it well. The do it in response to an input. You can reason about them. You can make predictions about them. They don’t surprise you. And when the fail, they fail in very specific, predicable, handleable ways. Which means if it does something unexpected, it’s easy to figure out why. Then you can figure out how keep it from doing that. And make it even more predictable.

If you build something that way, something that has very narrow inputs and only a few outputs, the space it operates in, its operational domain, is very small. The smaller the operational domain, the less complex the behavior. And if one part is less complex, the rest of the system can be less complex. The more things you can make less complex the more you can make other parts less complex. It’s a virtuous cycle.

I can hear you saying that making things less complex is great and all, but the problems we’re looking at are complex, and we need to deal with that complexity. That’s true. Things are complex. We need to deal with them. The thing is, we need to deal with them at the system level, not the component level. We all want to build the big, new, shiny, complex, solution to all the world’s problems in one fell swoop, but that’s unlikely to be the best answer.

You can combine all those simple components in complicated ways. Consider the computer I’m using to create this entry. At its core, it’s a collection of gates. 1’s and 0’s. There are lots of them, and they’re connected in very complicated ways. And I can do almost anything with them. But complication is something we can deal with. Complicated things are knowable. And that’s the key.

We can almost always handle complex behavior with a complicated arrangement of simple, straightforward steps. It’s only for the rest of the cases that you need to build a complex solution.

So is your complex problem one that can be solved with a complicated arrangement of simple things, or do you need a complex solution. The answer to that question is “It Depends”.