The retrospective is the heartbeat of the project

The retrospective is the heartbeat of the project

Sometimes it beats slowly, sometimes quickly. Sometimes it thumps desperately, sometimes it whispers. Sometimes a doctor is listening.

But if it stops, the project will be in trouble. The work may still get done by the individuals on the team, but it will no longer be done by the team itself. One nerd goes one way, one nerd goes the other way. Their efforts collide and cause problems that take more time to unwind than they would have ever spent communicating about things up front, a few minutes at a time.

In the retrospective, people on a team hear each other’s ideas, catch each other’s mistakes, and win each other’s esteem. Great software is created by a team that performs as a single entity, and the retrospective meeting is its heartbeat.

Your heart is the hardest working muscle in your body. It does not stop when you sleep, when you eat, when you work, when you are happy, when you are afraid, or when you are devastated.

When you are exhausted, it does not stop to save energy. It stops when you are done with your body.

It will never save any time or money to stop the heartbeat of the project.

If you really think your team doesn’t need to have a retrospective meeting every couple of weeks, prove it. With science. Stop retrospecting for two weeks. At the end of the sprint, talk with your team about how it went. If it was awesome, commit to skipping it again until the next sprint.

Efficiency vs. Effectiveness

Say you need money. Lots and lots of money.

You could rob a bank. Assuming you were skilled/lucky enough, you could have the money in hand right away, and for a minimal investment of time and effort. This is efficient.

On the other hand, you could study, practice, work, and connect for years to build a career, and a reputation. You would accrue the money more slowly, and with a great deal more upfront muscle and patience. But the likelihood of you being hunted like an animal, your bounty being reclaimed by lawmen, and your life being ruined is orders of magnitude lower. This is effective.

The choice between efficiency and effectiveness in our day to day work rarely presents itself with this level of clarity. Pressure to deliver more, faster, and cheaper blurs the line even further.

But delivering something today that crumbles tomorrow has no value. It is unprofessional, and it erases the trust you may have heretofore built with your audience.

So, what does this have to do with software?

IMG_2468

Signing off on an exhaustive, up-front specification document is efficient.

Adding the next most important feature, one at a time, is effective.

Writing legacy code is efficient.

Writing test-driven code is effective.

One big go-live at the end of the project is efficient.

Shipping working software early and often is effective.

Each of the bold choices above is sure to trigger resistance in traditional management. These options sound like extra time and money, like unnecessary detours from the straight line between points A and B that they may have imagined the work of software to be. And that is understandable, if all that has ever been emphasized in their work is a lock-step bottom line that would make Fredrick Taylor blush.

It’s not about right or wrong, smart or stupid, good or bad. It’s about balancing short term and long term. It’s about whether we care about delivering value, responding to change, and building trust, or if we’re just here to punch the clock today, make the sale today, and not ruffle any feathers today.

Agile is not hard-coded

Agile. It’s right there in the name. And yet, it could be the most overlooked thing in plain sight for your team, sprint after sprint.

Both nerds and those charged with herding them look to Agile prescriptions like Scrum or Kanban to solve their problems. Months or years wasted on a project that never delivers any value. Disengaged teams that point fingers and sling tickets over walls. A product that is wrong or irrelevant by the time it sees the light of day. Yes, Virginia, Agile can make these monsters go away.

But only if you let go of it.

In a world where your next move is dictated by a rigid process framework that management three levels above your pay grade has signed off on, it’s easy to see where Agile breaks down. After all, it’s just another process.

If, however, it is understood to be a mindset instead, one where the process itself is measured and tweaked by the team every two weeks to suit the work, an agile approach can drive the continuous delivery of value, up everyone’s communication game, and foster the engagement of every member of the team.

Agile is not a hard-coded process. It is a mindset and a tool set that can help a team to deliver a valuable product, early and often. As soon as it is a process etched in stone for every team across the company, it ceases to be agile. And it ceases to be different from any other process that your company has been sold.

The Primary Value of Software

I chose… poorly.

My team has been pulling out stops all winter long to build a cutting edge single-page app for a very important client. Suddenly, earlier this month, the SPA framework I picked officially white-flagged it.

poorly

Yet, in spite of this and plenty of coffee, I sleep like a baby.

But isn’t this the nightmare scenario that our parents and managers warned us about when we started using open-source libraries? What if the sole proprietor of the project gets hit by a bus? What if the poor schlub making this thing for free wakes up and gets a real job? What if? They’re all going to laugh at you.

Oh, logic from 2007. Adorbs.

Of course I care about the app, and the long-term implications of the tools we choose for it. But I’m not uptight about having chosen the “wrong” SPA framework for our client because my team and I are clear on what really makes software valuable. And we work hard to ensure that our app has it.

What makes software valuable?

This is an idea that I picked up from “Uncle” Bob Martin’s phenomenal Clean Code series. It has changed the way I view my work, and I hope it does the same for you.

Ask just about anyone in our industry what gives software its value, and they’ll tell you its all about solving problems for users. And they would be right–solving problems makes the software valuable, and most folks who pay for software likely believe that this is the extent of what they are paying for.

But solving a problem that the user has today is the secondary value of software.

epiphany

The primary value of software is that it is soft. That it is resilient in the face of inevitable change. That it not only meets the users’ requirements and solves their problems in the present tense, but that it can be readily adapted to meet needs that will arrive tomorrow, or the next day.

But this doesn’t just happen.

So, this is amazing news, right? Our software has a value we didn’t even know was there–let’s charge more for it!

Not so fast, there, Steve. This primary value thing is what makes software the bee’s knees, but it doesn’t occur naturally just because you’re writing some code. Most systems do not possess this quality.

What does it take, then? Planning for every possible permutation of our application’s future? Clairvoyance sufficient to pick the winning stack? Infinitely configurable options?

No, thank Turing. In order to unlock the primary value of software, the code from which it is built must be clean.

He’s doing it again

Man, I sure keep playing that clean code fiddle, don’t I?

And with good reason. It’s not because I am selfishly obsessed with the placement of brackets, spaces v. tabs, or the intricate contours of my navel, however engrossing each of those subjects may be. It’s not about preaching some esoteric set of nerd rules. It’s about long-term vs. short-term thinking.

Software Craftsmanship is ultimately about the value of software. Only clean code, code that respects the SOLID principles, code that is covered by tests in the way that only test-driven code can be, can stand up to change over time and truly yield this value. Whether that change comes from a shift in the nature of the users’ problem set or in the fickle wind that blows a new de facto standard library across our desks.

No warm milk for me, thanks

So we code clean and keep it clean. Our framework-y plumbing code depends on our valued domain logic, rather than our domain logic residing within framework-dependent code. And every new feature begins with a design conversation and one failing test at a time.

Between that and Good-Guy Eisenberg‘s generous plans for Durandal that make it more of a finished project than an abandoned one, my team is looking at a pretty nice-to-have problem in Angular taking the title.

firstworldproblemsgirl

So yeah, I’m getting my eight hours. Are you?

Think Like A Functional Programmer For Better Object Oriented Code

The benefits of functional programming have been touted up one side of the nerdosphere and down the other. But when I picked up a little F# last month, I uncovered one that wasn’t printed on the tin.

What I found was that while functional languages like F# make it easy to fall into the pit of success with FP, the languages themselves are not the gatekeepers to the mindset, techniques, or payoffs of programming functionally with a capital F. If your boss won’t let you throw down in Clojure just yet, scoot a little closer and let me show you how you can get some of that FP awesome to rub off on your scabby old C# today.

Not what they mean by overloading, you guys

So, here we have a typical function from a typical OO codebase. That stretching sound you hear is me calling this code object-oriented–this pasta is downright procedural.

public void SetPrimaryUserTo(User newPrimaryUser) 
{
    // is the current user the primary user?
    if (_currentUser.IsPrimaryUser || _currentUser.UserRole == ApplicationRoles.FirmOwner) 
    {
        // does the new primary user belong to the same firm?
        if (newPrimaryUser != null && _currentFirm == newPrimaryUser.Firm) 
        {
            // reset all users' primary flags
            foreach (User user in _currentFirm.Users) 
            {
                user.IsPrimaryUser = false;
            }
 
            newPrimaryUser.IsPrimaryUser = true;
 
            // notificate
            var notifications = new Notifier();
            notifications.Send(newPrimaryUser, "Congratulations!  You're the new primary user for your firm!  Remember: with great power comes great responsibility.");
        }
        else 
        {
            throw new Exception("User does not exist.");
        }
    }
    else 
    {
        throw new Exception("You are not authorized to do that.");
    }
}

dr-evil-function

If you squint long enough, you can make out that our thirty-odd lines of grunt here is responsible for the following.

  1. Switching a firm’s primary user status from one user to another,
  2. Making sure that the current user has the privilege to do so,
  3. Making sure that the new user exists and belongs to the same firm as the current user, and
  4. Notifying the new primary user after the switch has been made.

And boy, are its arms tired. #badumpbump

Seriously, folks. It juggles responsibilities like cloned Michael Keatons. The generic exceptions being thrown are nowhere near the inscrutable if blocks that trigger them and that first comment is a lie by omission. It smells like nobody loves it.

But what could a sagacious and popular developer such as yourself do about a tragic snippet such as this?

Make it func-y

Usually the first thing about functional programming that gets an OOP lifer’s dander up is that the variables are immutable by default. Just to underscore that: you cannot (and should not) change the value of a variable in functional programming.

How, then, does the functional programmer ever get anything done? With functions. Nootch.

let x = 9
let z = add x x
assert (18 = z)

Except now we’re not talking about functions like the homunculus Dr. Evil was taunting a few paragraphs back. Functional code would never get off the ground if that was a function. What makes FP tick at scale is that its functions are small and discrete, designed to be composed together to achieve a larger goal.

Put another way? Stop me if you’ve heard this one before. They are responsible for doing exactly one thing. That’s right–functional programming and the Single Responsibility Principle are totally sittin’ in a tree.

Keeping that in mind, let’s get our Extract Method on with SetPrimaryUserTo:

public void SetPrimaryUserTo(User newPrimaryUser) {
    if (!HasPermissionToReassignPrimaryUser(_currentUser))
        throw new UnauthorizedAccessException();
 
    if (!UsersAreInTheSameFirm(_currentUser, newPrimaryUser))
        throw new UserDoesNotExistException();
 
    AssignPrimaryUserStatus(newPrimaryUser);
    Notify(newPrimaryUser, NewPrimaryUserNotificationMessage);
}
 
private bool HasPermissionToReassignPrimaryUser(User user) {
    return user.IsPrimaryUser || IsFirmOwner(user);
}
 
private bool IsFirmOwner(User user) {
    return user.UserRole == ApplicationRoles.FirmOwner;
}
 
private bool UsersAreInTheSameFirm(User user1, User user2) {
    if (user1 == null || user2 == null)
        return false;
 
    return user1.Firm != user2.Firm;
}
 
private void AssignPrimaryUserStatus(User newPrimaryUser) {
    foreach (User user in _currentFirm.Users) 
        user.IsPrimaryUser = false;
            
    newPrimaryUser.IsPrimaryUser = true;
}
 
private void Notify(User user, string message) {
    var notifications = new Notifier();
    notifications.Send(user, message);
}
 
private string NewPrimaryUserNotificationMessage {
    get {
        return "Congratulations!  You're the new primary user for your firm! Remember: with great power comes great responsibility.";
    }
}

Of course, the FP-savvy among you are currently pushing up their Warby Parkers and calling me out on the fact that this code is not really functional. Why, there’s state change a-plenty in AssignPrimaryUserStatus, for one thing. And we’re not doing that thing where we pass functions into other functions. Or even pretending to with LINQ.

What we have done, though, is that we have taken a sizable page from the FP playbook and used it to grow our C# into more composable, more resilient (and thus more valuable) code. Still don’t see it?

Right. You asked for it.

Aaaaaand here’s the part where I throw in some new requirements to see how our code reacts

  1. Users must be Owners to be assigned primary status.
    public void SetPrimaryUserTo(User newPrimaryUser) {
        if (!HasPermissionToReassignPrimaryUser(_currentUser))
            throw new UnauthorizedAccessException();
     
        if (!UsersAreInTheSameFirm(_currentUser, newPrimaryUser))
            throw new UserDoesNotExistException();
     
        if (!IsFirmOwner(newPrimaryUser))
            throw new UserNotQualifedForPrimaryException();
     
        AssignPrimaryUserStatus(newPrimaryUser);
        Notify(newPrimaryUser, NewPrimaryUserNotificationMessage);
    }
     
    // ...
  2. The new primary user is notified when their throne has been usurped.
    public void SetPrimaryUserTo(User newPrimaryUser) {
        if (!HasPermissionToReassignPrimaryUser(_currentUser))
            throw new UnauthorizedAccessException();
     
        if (!UsersAreInTheSameFirm(_currentUser, newPrimaryUser))
            throw new UserDoesNotExistException();
     
        if (!IsFirmOwner(newPrimaryUser))
            throw new UserNotQualifedForPrimaryException();
     
        AssignPrimaryUserStatus(newPrimaryUser);
        Notify(newPrimaryUser, NewPrimaryUserNotificationMessage);
        Notify(_currentPrimaryUser, ItAintYouAnymoreNotificationMessage);
    }
     
    private string ItAintYouAnymoreNotificationMessage {
        get {
            return "Oh noes! You are no longer the primary user.";
        }
    }
     
    // ...
  3. The current primary user is notified when an unauthorized power grab has been narrowly averted.
    public void SetPrimaryUserTo(User newPrimaryUser) {
        if (!HasPermissionToReassignPrimaryUser(_currentUser)) {
            Notify(_currentPrimaryUser, FailedCoupNotificationMessage);
            throw new UnauthorizedAccessException();
        }
     
        if (!UsersAreInTheSameFirm(_currentUser, newPrimaryUser))
            throw new UserDoesNotExistException();
     
        if (!IsFirmOwner(newPrimaryUser))
            throw new UserNotQualifedForPrimaryException();
     
        AssignPrimaryUserStatus(newPrimaryUser);
        Notify(newPrimaryUser, NewPrimaryUserNotificationMessage);
        Notify(_currentPrimaryUser, ItAintYouAnymoreNotificationMessage);
    }
     
    private string FailedCoupNotificationMessage {
        get {
            return "Someone is fully out to get you. Thought you should know.";
        }
    }
     
    // ...

All right, so our app doesn’t exactly smell like team spirit. But its code sure can look change in the eye and yawn.

Even if you’re nowhere near a Haskell compiler, thinking like a functional programmer is good for you and your object-oriented code. Not only will it make your code more vital and attractive to its potential mates, but it’ll also limber up your gray matter so that when the day finally comes for you to hot swap a little Erlang, you’ll be all over it.

I just helped some third graders learn how to code. Here’s what they taught me.

In December, during CSEdWeek, I had the privilege of leading my daughter’s third grade class in the Hour of Code, an event in which hundreds of thousands of aspiring nerds worldwide descended upon the web’s finest coding tutorials to learn what all the fuss is about.

A few seeds may have been planted that day. But Mrs. Herr’s third graders weren’t the only ones who learned something–here are just a few things that they cleared up for me.

We have the same problems that third graders have when it comes to working together. We just hide them better.

When we began, the tutorial was queued up on each of the classroom’s thirty-one iPads, one per student. I’m big on pair programming, though, especially in a situation where there’s learning to be done–and there’s always learning to be done. So I asked that the children put half of the iPads away and work in pairs–one student would drive, working the controls on the screen, and the other would navigate, hands-off, using their words to do the work with their partner.

As the children worked like this, patterns emerged that I recognized from my own pairing adventures. And nine-year-olds don’t hold back the way professional adults have learned to do, so the natural tension between driver and navigator was on display.

It became clear that each member of the pair was working on two problems simultaneously.

pair-programming

The driver was solving the software problem at hand mentally, while also working with the device mechanically to provide input or to reveal information. The navigator was also solving the software problem at hand mentally, while working to communicate verbally with the driver and not touching the computer.

That last part was a challenge for some of the navigators. Some in our profession (present company excluded of course, dear reader) might relate.

The creative tension in a programming pair is the pull of working on the common problem with your partner combined with the push of struggling with a problem that your partner does not have. The most successful pairs showed both solid communication and patience with their partner’s “other” problem.

You won’t process what just happened if you don’t retrospect.

After about forty minutes of dragging and dropping together if/else and repeat blocks to move Angry Birds and Zombies through mazes, Mrs. Herr asked the children to stop. She took the time to point out that focusing on intense problems for an extended period of time is hard on our brains, that it was okay to feel frazzled, and that it was time to stop and discuss what had just happened.

So the children sat on the floor, and we talked. We talked about what went well, and what didn’t. The room lit up a bit as children shared their struggles, and discovered that they weren’t the only ones who had them.

Our little chat also helped the students to put this fresh experience in perspective. Many of the questions they had for me were mostly of the “is this really what it’s like” variety, and they seemed hungry to put what they had just done into a real-world context, to hang on to it and understand it better.

Grown-ups need this, too. Making the time to retrospect after solving a challenging software problem (or working with challenging people) is a reboot for your brain. It refreshes you and your team, putting what just happened in context, and allowing you to see what did and didn’t work with clarity. It’s a release valve for pressure that would otherwise burn you out, and it feeds the quality of your work to come.

The best way to understand is to teach.

A few of the pairs made it all the way through the twenty exercises in the tutorial, and did so with time to spare. We had these budding code ninjas walk around to the other tables, and coach those who were still working. During our retrospective discussion, I noticed that these kids tended to be more engaged, and had more insight into the activity.

The best way to learn something is to do it, and the best way to truly understand something it to teach it. There is nothing like organizing information enough to present it successfully to another human being to firm it up in your own mind.

I don’t share what I’ve learned here because I am an expert. I do it in an effort to become one.

Thanks to Jynnette Herr, Mrs. Herr’s third graders, and Diane Dikeolakos at Arlington Elementary School for their time and attention, and for helping me to understand my work a little better.

How to Handle Exceptions in ASP.NET Web API Like a Gentleman

Ah, the yellow screen of death.

YSOD

It’s a sure sign of an ASP.NET dev who has not taught their app to use its indoor voice. And there are many fine (and elsewhere documented) methods for dealing with a wayward exception before it turns your entire user interface into ketchup and mustard.

But I’m not here about that yellow screen of death.

HTTP 500 is the new YSOD

In a “modern” web app (as the kids these days call them), it’s much more likely that an uncaught something or other will poot forth from behind a REST API, presenting as a blob of JSON rather than as rendered markup.

Out of the box, ASP.NET Web API gift-wraps our code’s uncaught excremental output with an HTTP 500 response whose body contains more information than the consumer of the API probably needs:

HTTP 500 Internal Server Error

{
    "Message": "An error has occurred.",
    "ExceptionMessage": "No ticket.",
    "ExceptionType": "System.ArgumentNullException",
    "StackTrace": "   at IndianaJones.LastCrusade.Web.Api.TicketsPleaseController.Get() in TicketsPleaseController.cs:line 45\r\n   at lambda_method(Closure , Object , Object[] )\r\n   at System.Web.Http.Controllers.ReflectedHttpActionDescriptor.ActionExecutor.<>c__DisplayClass13.<GetExecutor>b__c(Object instance, Object[] methodParameters)\r\n   at System.Web.Http.Controllers.ReflectedHttpActionDescriptor.ActionExecutor.Execute(Object instance, Object[] arguments)\r\n   at System.Web.Http.Controllers.ReflectedHttpActionDescriptor.<>c__DisplayClass5.<ExecuteAsync>b__4()\r\n   at System.Threading.Tasks.TaskHelpers.RunSynchronously[TResult](Func`1 func, CancellationToken cancellationToken)"
}

This is the new Yellow Screen of Death. A RESTful sort of interface (the sort the Web API framework is built to deliver) should instead embrace and leverage its protocol, not work around or ignore it, as this default behavior does.

A more RESTafarian approach would be to return a slimmer response, perhaps composed of just the Exception’s Message property for the body, and (more importantly) bearing an HTTP Status Code that aligns with the nature of what’s actually gone awry. For instance, if bad user input was to blame, return a 400 (Bad Request). If a query for an specific record comes up empty, a 404 (Not Found) applies. And if somehow in the course of its operation your application suddenly became a whistling kettle of hot water, you could always send back a 418 (I’m a Teapot).

Web API makes doing this a piece of cake, by way of the HttpResponseException and its little friend, the HttpStatusCode enumeration:

public class TicketCollector {
 
    public void CollectFromPassenger(Ticket ticket) {
        if (ticket == null)
            throw new HttpResponseException(HttpStatusCode.BadRequest);
 
        // TODO: take ticket
    }
}

Now, make it right

As you can imagine, if we adopt this pattern across our codebase, our business logic will become shot through with references to System.Web.Http and HttpResponseException. Nasty.

I mean, business logic code is hands-down the most valuable part of any app, because it defines the features that are the application’s very reason for being. This code should be completely agnostic to from whence its input has come, and to how its output is ultimately being presented. If we want our app to be resilient and sustainable, we’ll have to unhitch this code from the System.Web.Http wagon.

We can accomplish this by updating our precious, precious logic to throw non-HTTP type exceptions. Then, in our Web API, we can catch these and translate them into HTTP exceptions as appropriate. Anything HTTP is solely the concern of the API code, and this division of labor keeps it that way.

public class TicketCollector {
 
    public void CollectFromPassenger(Ticket ticket) {
        if (ticket == null)
            throw new ArgumentNullException("ticket", "No ticket.");
 
        // TODO: take tickets, avoid Nazi eye contact
    }
}
 
// meanwhile
 
public class TicketsPleaseController : ApiController {
 
    public void Post(TicketRequest request) {
        try {
            var indy = new TicketCollector();
            indy.CollectFromPassenger(request.Ticket);
        }
        catch (ArgumentNullException) {
            throw new HttpResponseException(HttpStatusCode.BadRequest);
        }
        catch (Exception e) {
            throw new HttpResponseException(HttpStatusCode.NotAcceptable);
        }
    }
}

Concerns were separated, exceptions were handled, and lives were literally saved, you guys. But at this point, we’re only two-thirds of the way through the article–and that means we can do better.

Exception handling is not a feature

As our codebase evolves, this pattern will grow hair fast. The API’s pipes are getting clogged with prickly and distracting try/catch blocks. Even in our simple example above, there are eight lines of code dedicated to exception handling, compared to just two that relate to the actual meat of the call.

Exception handling is not a feature of our app, it is a cross-cutting aspect of it. Our code should reflect this by sweeping this aspect out of the way and returning focus to the feature. We can do this by rolling a custom ExceptionFilterAttribute:

public class HandleExceptionAttribute : ExceptionFilterAttribute {
 
    public Type Type { get; set; }
    public HttpStatusCode Status { get; set; }
 
    public override void OnException(HttpActionExecutedContext context) {
        var ex = context.Exception;
        if (ex.GetType() is Type) {
            var response = context.Request.CreateResponse<string>(Status, ex.Message);
            throw new HttpResponseException(response);
        }
    }
}

Now, just as our logic burns clean and knows nothing of HTTP, our API reads as just the plumbing we need it to be:

public class TicketsPleaseController : ApiController {
 
    [HandleException(Type = typeof(ArgumentNullException), Status = HttpStatusCode.BadRequest)]
    [HandleException(Type = typeof(Exception), Status = HttpStatusCode.NotAcceptable)]
    public void Post(TicketRequest request) {
        var indy = new TicketCollector();
        indy.CollectFromPassenger(request.Ticket);
    }
}

We can even stack several of them up in the order they should be handled, just as we do with multiple catch blocks.

The pool of available HTTP Status Codes may be limited, especially when compared to the limitless horizons of wrong your software may decide to throw. But with a little creativity, most levels of jacked-up can be conveyed just by using HTTP well. And with our HandleExceptionAttribute in the bag, there are no more excuses for rolling the HTTP 500 of Death.