Forem: Joe Petrakovich

Adding a second line of business: Refactoring Strategies

Joe Petrakovich — Tue, 05 Nov 2019 00:00:00 +0000

In the Lessons Learned case study, we discussed the high level logistical issues driving my team’s decision to add a second line of business to an existing application.

In this article, we’ll go over the code-level refactoring steps involved in this very large and high risk project. If you find yourself in a similar position to the one in the above article, you can use the techniques in this guide to make the process a lot easier.

Safely extracting subclasses from a 10,000 line God Object

For consistency, we’ll continue to use the car insurance & home insurance examples from the case study.

In our example, our application’s main line of business was car insurance, and although there were a lot of car insurance related business concerns scattered throughout, there were also a lot of generic entities that could be shared across the insurance landscape. These are things like insurance agents, insurance companies, insured businesses and people, notices, payments, and most other accounting-related entities.

In this application, we found that there were two root objects that tie everything else together. We found that every customer was managed first through a quoting process via a Quote object, and if the quote was accepted, it became an Account. All business was conducted through these objects. These Quote and Account objects also had database primary key IDs that spread throughout most other objects.

In your case, you likely have at least one object like this.

We found that these root objects were heavily laced with car insurance concerns, so to add a second line of business in a way that would allow us to continue using Quote and Account as the main business vehicle (no pun intended), we decided to convert both Quote and Account into abstract base classes, and have the application work with CarInsuranceQuote, CarInsuranceAccount, HomeInsuranceQuote, and HomeInsuranceAccount subclasses instead.

By extracting subclasses and leaving any shared properties and methods in the base class, we were also priming the system to accept future lines of business as well. Adding boat insurance would simply involve implementing BoatInsuranceQuote and BoatInsuranceAccount subclasses.

The remainder of this article will look at what it took to extract subclasses from just one of the above classes (the Quote class), as you’ll only have to repeat the process for any others.

Step 1: Creating The Line Of Business Distinction

The very first step involved when adding a second line of business to an existing application is to make your application aware of the concept of lines of business. Your app will need a way to distinguish between the two, and since your app has only ever been the original line (car insurance, in our case), it makes sense to initialize all existing Quote objects as belonging to that line.

The easiest way to do this is to add an enum property that represents each line of business, and initialize all existing objects to be of the original line.

public enum LineOfBusiness { CarInsurance = 1, HomeInsurance = 2 }

public class Quote
{
    public LineOfBusiness LineOfBusiness { get; set; }

    //...
}

And the supporting schema changes…

ALTER TABLE Quotes
ADD LineOfBusiness int NOT NULL
DEFAULT (1) --init to existing line of business

You’ll also likely need to modify your ORM or any persistence code for saving/loading this property.

Step 2: Constructor Madness

Now that your app is LOB-aware, it’s time to convert your original class into an abstract base class and bring about the existence of the line of business child classes.

First, make your original class abstract, along with the LOB property we created in the last step.

public abstract class Quote
{
    public abstract LineOfBusiness LineOfBusiness { get; }
}

Then, create a child class for each of your planned lines of business. You can permanently set the line of business since it will never change when using this object.

public class CarInsuranceQuote : Quote
{
    public override LineOfBusiness LineOfBusiness => LineOfBusiness.CarInsurance;
}

public class HomeInsuranceQuote : Quote
{
    public override LineOfBusiness LineOfBusiness => LineOfBusiness.HomeInsurance;
}

//any others?

Spawn the children!

This step is called Constructor Madness because if your app has been using plain old constructors to create new and/or load existing objects for use, the abstract class conversion will instantly cause a lot of compiler errors.

Being 20-years old, our app was created using the Active Record design pattern, which means that objects are responsible for handling their own persistence (they save and load themselves by interacting directly with the database).

If your app is using an ORM, you may have it slightly easier.

Quote existingQuote = new Quote(existingQuoteID);

var q = new Quote(); //these no longer work...

There are a couple ways to handle this:

1) Create a static factory method on the base class that works out which child class to instantiate based on the line of business. Then replace all usages of new Quote() with the factory method.

public static Quote GetExisting(int quoteId)
{
    var lineOfBusiness = GetLineOfBusiness(quoteId);

    switch (lineOfBusiness)
    {
        case LineOfBusiness.CarInsurance:
            return new CarInsuranceQuote(quoteId);

        case LineOfBusiness.HomeInsurance:
            return new HomeInsuranceQuote(quoteId);
    }
}

Or…

2) Assume most existing constructor usages in your code were designed for the original line of business, so just replace new Quote() with new CarInsuranceQuote().

var existingQuote = new CarInsuranceQuote(existingQuoteID);

var q = new CarInsuranceQuote(); //ahh, all better...

We ended up doing a bit of both.

In our case, it turned out that most of the constructor usages were on user interface pages, and because we decided we would make brand new pages for the new line of business, the reality was that in most cases we could simply replace the old Quote constructor usages with CarInsuranceQuote constructors.

Since the system was built for car insurance for 20+ years, it is safe to assume that using the car insurance subclass throughout the existing code will be appropriate.

If you’re not sure, just use the factory method and you can always change it later.

Plan to have to work through quite a bit of compiler errors. Take your time and commit often.

This refactoring is mostly a hefty exercise in leaning on the compiler. It’s in your best interest to make small changes and re-compile often in order to see what new errors turn up.

If you make too many changes at once, you’ll easily get overwhelmed at the multi-headed hydra of errors that recursively spawn out of each change and subsequent fix.

Change, recompile, fix, commit, repeat.

Active Record pattern woes

In our case, with the Active Record pattern, we also needed to make sure our child classes still made use of the base class’s existing save and load methods.

public abstract class Quote
{
    public void Save()
    {
        SaveInner();
    }

    public virtual void SaveInner()
    {
        //save properties
    }
}

public class CarInsuranceQuote : Quote
{
    public override SaveInner()
    {
        base.SaveInner();

        //save car-insurance-specific properties
    }
}

public class HomeInsuranceQuote : Quote
{
    public override SaveInner()
    {
        base.SaveInner();

        //save home-insurance-specific properties
    }
}

This meant that all our existing usages of .Save() and .Load() would continue to work and would handle all base class properties, as well as any properties specific to a child class.

Again, if you are fortunate enough to not have to use the Active Record pattern, you may not need to go through this much trouble.

Single vs. Class Table Inheritance

Another decision that will need to be made is how you will store the properties that are unique to your new second line of business.

If you’ve only been using one table for Quote, and you’re making use of a save and load strategy like in the last section, your persistence will need to work out which columns (or tables) to include or exclude depending on which object is being stored or retrieved.

Our application was already using single table inheritance in other areas, so we went with that. We also did not have experience with class table inheritance and felt that single table would be the easiest way to continue reusing existing relationships off the primary key.

At this point you will have two or more very thin child classes and one thick base class. It is now safe to begin using your child classes, but obviously they would not be of much use to you, as all the properties and methods are still in the base class and the distinction between the lines of business is no more than a name.

The final step in this process involves three kinds of modifications to the base class. They are:

1) Pushing down all of the properties and methods from the base class that belong exclusively in the original line of business subclass. 2) Converting some properties and methods to be abstract, with custom line-of-business specific implementations.3) Leaving any others behind that can be shared among all lines.

Step 3: Push down methods, properties, and fields (in that order)

After you’ve got your object constructors back in order, and your persistence set up to correctly handle the new hierarchy, the remaining work involves finding the proper home for the properties and methods that are all hanging out on the base class.

In our example scenario, because the application was originally built specifically for car insurance, that meant that a large majority of the properties and methods could be pushed down to live exclusively on the CarInsuranceQuote subclass.

After all is said and done, the base Quote class would be left with the few properties and methods that are shared across all lines of business. For us, that meant metadata properties like when the quote was created (and by whom), when it was last modified, user notes, helper/utility methods and several abstract member definitions.

Methods first!

Depending on how you chose to do the constructor step, this step could be the most time-consuming, since all your existing code is expecting these class members to exist on the Quote class.

Pushing down a single method could result in hundreds or more compiler errors!

To do this step without wanting to pull your hair out, you’ll find it works best to push methods down first, before trying to push properties or fields down. This is because a property or field likely has many more usages than a method, and a method might not depend on any fields, so moving it cause little to no errors. On the other hand, if you move a field or property, many things could depend on it and they will all error.

So methods first, properties second, fields last.

I believe I learned that tip (and the next one) either from Martin Fowler’s Refactoring book or Joshua Kierevsky’s Refactoring To Patterns book. Both are worth a space on your shelf.

Access modifier flipping for error reduction

When you’re pushing things down, you may see many errors related to usages of private members on the base class. An easy, short term fix is to simply make them protected. They will most likely be pushed down eventually, but you can use this access modifier flipping technique to quickly clear up compiler errors so you can keep moving forward with the refactor.

Depending on how large your base class is, this task will surely test your patience. You’ll be pushing down one field, generating a ton of errors, fixing them (which cause several more, and fixing those (which cause several more…(ad-infinitum)).

I recommend you go very slow, do one thing at a time, recompile often, and fix only those errors that come up from your single change. Once it compiles without error, consider doing a commit to lock in that change and begin another. If you get over-eager and try to do more than one at once, you’ll be looking at potentially hundreds or thousands of errors and you’ll get so overwhelmed trying to fix them that you could make a grave mistake.

I had to start over completely so many times because of this.

I’d get ambitious and try to do too many refactors at once and I’d get lost in a whack-a-mole recursive error hell where one fix would generate 50 more errors. Then I’d feel so uneasy about all the changes that I’d just git reset HEAD --hard and start over.

Small changes and commits!

Wrapping Up

Whew! We made it.

Let’s recap over some of the highlights of this refactor.

Check out the case study article to help you decide if doing this kind of refactor is the best decision for your team.

Your application will likely have one or more root objects that orchestrate the majority of the business processes and logic. These will be your splitting points. The goal is to extract a hierarchy of two or more subclasses that will each hold a separate line of business and that can make use of most of the accessory entities in the application (we benefited most from the reuse of the accounting and payment submodules).

Start by creating the knowledge of the line of business via a type enum. In our example, we went with a single-table inheritance model in our database using an LineOfBusiness descriminator column.

Next handle all the constructor issues that turn up once your existing class becomes an abstract base class.

Finally, use the methods-properties-fields order when pushing down members from the base class into the appropriate child class. I found that order to result in the least amount of headaches.

Keep the class refactoring books close by to reference the Extract Hierarchy, Extract Subclass, and Extract Superclass refactorings.

Once you’ve finished, it may be wise to only make use of your new line-of-business subclass within brand new UI pages so that you don’t break existing code.

Good luck!

Lessons learned adding a second line of business to a 20-year-old application

Joe Petrakovich — Mon, 30 Sep 2019 00:00:00 +0000

At some point in your career you’ll be tasked with a project that will strike fear into the very core of your soul.

It will require you to do things you’ve never done before, to make choices for which you have no former wisdom to rely on.

You’ll pour endlessly over ancient programming lore, online tutorials, articles, and blog posts, hoping you’ll find someone, anyone who has gone through the same scenario and can tell you exactly what to do.

And you won’t find it.

You’ll be all alone.

And if you don’t get it right, if you fuck it up – you’re toast.

I just came out the other end of this very scenario, alive and unscathed, and I’d like to shine some light on the topic in which it was born.

With the proper strategies and mindsets, you can be confident that you can handle this particular kind of problem. We’ll take a look at the problem itself, some of the strategies available to you, the path my team chose (and it’s present day result), and finally review the main lessons learned.

This article won’t cover the technical, code-level details of how it was done. If you’re interested in that part, it’ll be in an upcoming article. You can jump to the bottom and add your email and I’ll send you it when it’s done.

The Problem: Adding a second line of business to a 20-year old codebase

If you work for a company that is doing well, it’s common that it will expand into new markets.

For example, if you work for an insurance company that sells car insurance, it is not inconceivable that your company could eventually sell RV, boat, life, rental, or home insurance.

The timeline of when this branching out might occur could be within the first year of business, all the way until 100+ years down the line.

To understand the problem my team encountered, you can imagine that the software we work on has served only one line of business for 20 years. For the sake of example, let’s continue with the insurance example and say that this is strictly a car insurance business.

Architecturally-speaking, you have 20-years worth of components, classes, methods, and variables, all modeled around car insurance.

This sytem models things like automotive insurance policies covering car accidents, based on things like vehicle age, make, and model, insured driver history, where the car is stored, and how it’s used. Things like a policy’s status and lifetime. Recurring or one-time payments. All the accounting data for these transactions. This is your typical line-of-business application that has grown to support all the different departments in the company.

And since this software has been supported for 20 years, the business language and concepts can get heavily embedded, and on top of that it’s usually got a lot of legacy baggage being dragged along with each new release.

Now, after 20 years time, your car insurance company decides it’s going to start selling home insurance.

A new line of business.

Home insurance is of course still within the overarching business of insurance, but it is also quite different. Despite both businesses dealing with the act of of insuring, they have grown and developed separately, so the terminology is not always the same, the properties, statuses, and aging of policies is vastly different, and the way the insurance can be paid for follows substantially different rules.

About the only thing that is similar is the fact that they involve something called an insurance policy, and that there are entities like the people being insured (insureds), insurance companies, and agents.

For now, the company can get by doing things the old fashioned way with spreadsheets and file shares, but they’re looking to you to come up with something better in a relatively short amount of time.

How you accomplish this is entirely up to you, but there are a few requirements, and some obvious conditions that you’ll need to weigh carefully.

Constraints and other mentionables

The company needs something better than spreadsheets, relatively quickly (less than a year, preferably sooner).
This system will most likely need many of the same features as the existing system, when it comes to things like reports, mailing notices, and accounting data. It won’t need these things on day 1, but eventually.
The company has found a way to partially perform some of the home insurance business work using the existing system by pretending car insurance policies are home insurance policies, and various other mental hacks.
Your team is small, 1-2 developers, no QA, and you need to keep supporting the existing line of business.
Obviously don’t break the existing system. It runs the entire business.

Weighing Our Options

After thinking about the problem and it’s constraints for awhile, we determined that we had three practical options.

Option 1 (a.k.a New Toys) - Create a new application from scratch.

Option 2 (a.k.a Safe Duplication) - Branch the existing app source code into a new app and heavily modify it to work with the new line of business.

Option 3 (a.k.a Obvious But Hard) - Modify the existing app to support the new line of business side-by-side.

Each option had a plethora of positives and negatives, and even to this day I wonder if one of these options would have been better than the one we chose.

Next we’ll take a look at the pros and cons of each option and play plinko with the constraints until we end up with the decision.

Option 1 (New Toys) - Create a new application from scratch.

After years of working on ASP.NET Web Forms applications, and only getting to play with ASP.NET Core on the side, this option was obviously very appealing.

A new app would not disturb the existing app, it would allow us to take advantage of faster development (and deployment) practices, and it could become the training ground for all future development at the company, freeing us from the dying branch that is .NET Framework.

I even recall taking a few nights of my own time to whip together a starter app to work from, transferring many of the existing tables and POCOs into equivalent Entity Framework code-first versions.

It wasn’t all puppies and candy though. Building this as a new app would be a lot like rewriting an app from scratch (something that is rarely a good idea.)

This new system was going to share many of the existing features from the other system, so we’d need to duplicate a ton of it or find some way to share it via APIs. With that comes lots of testing. Testing that in theory was already done for 20 years to battle-harden the existing system. All those iterations of testing and bug fixing have to be redone for any features you duplicate into the new app.

Then comes maintaining this app with separate releases, and a host of other problems that come with having a small team working on multiple systems.

I think to do this option we would have either needed a dedicated team, or much more time. I would have liked this route, but in the end, there was way too much meat and potatoes in the existing app that we would have missed out on, and so we passed on it.

Option 2 (Safe Duplication) - Branch the existing app source code into a new app and heavily modify it to work with the new line of business.

This option was more like converting a school bus into an apartment rather than a refactor.

We would branch the code into a new repository, and then play hack ‘n slash to convert all the car insurance behavior and appearance into it’s home insurance counterpart.

There were many benefits to this strategy. It would be safer because we’d leave the proverbial nest of our original application. Any bugs would be isolated from the main application, and that was quite enticing. All throughout my research I clung to this idea as a safety net because I was afraid my lack of experience with large refactorings would inevitably lead to a ball-of-mud situation.

Further, this option may have been the fastest to reach a version 1, as we’d only need to modify the quirks that the business already knew about by trying to force home insurance into the existing application’s domain. A lot of the code changes would be adaptations of existing behaviour and UI, rather than entirely new code.

The downside with a second branch is that it would heavily complicate deployment and the sharing of features and bug fixes.

Any bug you fix must be fixed and tested in both branches. If there are large differences between two areas where the bug exists, it may not be as easy as a git merge. It could require some finesse. And often you simply might not have enough time or resources (see above: small team).

The same is true for new features. Both systems may not be able to get them at the same time (or ever), so you end up playing a game of cat and mouse to keep them in sync.

Every fix and feature has to have the added conversation “Should we do put it on the other system too?”.

If possible, you could pull certain features out into separate shared libraries, but again, you need time and resources for that, and the stickiness of a 20-year old system isn’t as welcoming to that path.

We did not choose to go this route, although to this day I wonder if we would have had a version 1.0 out the door months earlier. And as we implemented the option we did choose, this option was still appealing as a way to jump ship in case things started to get bad.

There were times where I felt very unconfident that it would turn out well, and the fear of creating a ball-of-mud kept this option in my periphery.

Option 3 (Obvious But Hard) - Modifying the existing app to support the new line of business side-by-side.

This option was the first to arise because the business folks had already explained that they were able to sort of use the existing application on top of a new database by playing pretend with the existing features. For example, because the system allows for custom car insurance policy coverages, they could simulate home insurance coverages and make due with the random vehicle and driver references in the user interface here and there.

In the end though, it was merely a familiar place to store some data, arguably better than an Excel spreadsheet, and it didn’t help automate any of the real home insurance business processes.

But because we could see it in action, it was clear that the existing application had a lot of similarities and usable meat and potatoes, so figuring out how to refactor it to support two lines of business seemed plausible, although daunting.

There was sooooo much car insurance jargon and concerns laced throughout this 20 year old juggernaut.

Using some DDD terminology, from a higher level we could see that the existing line of business and the new line of business shared the same primary aggregate roots in concept. I.E. both lines of business revolve around the lifetime of an insurance policy.

The fundamental policy quote and policy account aggregate root classes on the existing application acted as the glue, tying together all other entities and transactions, they simply differed in properties and behavior.

It turned out that there were a few different ways we could do this modification.

We could A) simply add all new code and create new interfaces for things we wanted to reuse from the existing system.

B) Refactor it so that the differences between car insurance and home insurance were abstracted away via techniques like the strategy pattern or plain old inheritance.

Or C) The rapid ball-of-mud-inducing option of modifying existing code via basic if-else statements scattered everywhere to accommodate differences in behavior and appearance.

Because I was absolutely terrified of turning this 20-year-old beast into a ball-of-mud, I was staunchly against option C, and rightfully so. But it is unfortunately an option many will take. In my desperate attempt to find guidance with this project, several developers even recommended it via something like “Hey man, the code is probably not that great anyway, just add a bunch of if-elses. NBD.”

Option A sounded nice in theory. Adding new code is always safer than modifying existing code. All living in one app would allow us to have simple deployments, and we could still share code and features, albeit needing to write new interfaces for them.

The downside of option A had to do with the fact that the fundamental car insurance policy quote and account classes were deeply engrained throughout the app via their primary keys.

QuoteID and AccountID lived in almost every table, every class, as a reference back to the primary policy it originated from.

If we were to create brand new classes for home insurance in order to keep isolated from car insurance, we would need new interfaces for almost every existing feature, meaning we wouldn’t really save the time we were intending by sharing.

We’d also have to sprinkle new IDs all throughout the existing tables and classes.

Yuck.

And what happens if our business expands again to a third line of business?

Option A was not scalable with the business in that sense.

Of the three options for modifying the existing application, option B had the most chance for success. Abstracting away the differences between car and home insurance, whilst maintaining the base concepts of policy quotes, accounts, payments, insurance companies, agent, and insureds, simply felt right.

If done correctly, it would make sharing code and features almost automatic, and would also support an infinite number of additional lines of insurance business. Those precious QuoteID and AccountID primary keys could be maintained and shared between any new line of business.

It seemed like a no brainer. It even fit all the classic examples of inheritance structures we learn about in computer science classes or software design books. Base class of insurance policy, child classes for specializations (car insurance, home insurance.)

Duh, right?

Although this option seemed fitting, I had zero experience taking on a refactor of this size. And when I encounter the unknown, it puts me into a kind of robotic dissociative state where my body becomes an afterthought to my mind’s rabid information thirst.

I consume everything I can on the topic to ease my discomfort of not knowing, hoping I’ll find some wisdom that points the “one true way”.

Massive fear and lack of experience was a solid barrier to this option.

The Chosen One

After matrix brain downloading endless books and blogs to overcome the dread of unknowning, it was time to set forth on a plan.

Ultimately, based on our small team and the 20-years of features and bug fixes we wanted to make use of, we decided to try option 3. We would set forth refactoring the existing application so that it could handle multiple lines of business, share code between those lines, and keep deployment simple.

We also laid down some guidelines for this project to ensure we wouldn’t break the existing system in the process.

These were things like:

Other than splitting the fundamental aggregate root classes into two (to share QuoteID and AccountID, remember?), resist modifying existing code and pages. Just about all business logic is specific to a line of business, so trying to reuse it would be high risk and an if-else nightmare. If it has the smell of car insurance, avoid it if at all possible.
Similarly, always lean towards creating brand new code, pages, stored procedures, dependencies, etc. New code is low risk because it doesn’t interact with existing code.
There will be times where existing code can be shared and may need an adjustment, if this is the case, do so with great caution, write tests beforehand, and be confident it is truly a shared business concept. Never try to shoehorn an existing feature to work in the other line.

Further, while I tried my darnedest to use delegation over inheritance, I ultimately couldn’t make it work the way I wanted to, so I went for a more traditional use of inheritance to break our aggregate roots apart.

This meant converting two massive 10,000+ line god objects into abstract base classes, extracting two line of business subclasses, and very slowly pushing down all variables, properties, and methods that were exclusive to each subclass, while leaving any metadata-like shared property and behavior in the base class.

This was daunting and resulting in a lot of git resets where I’d start over from scratch to get a cleaner run. Keep an eye of for an upcoming article that details the strategy for this large and risky undertaking.

At first we did this refactoring gradually, meaning that we made use of the new line of business subclass even before all the existing line’s concerns were pushed down from the base class. This was an unsettling experience because it meant any developer could make use of (or be confused by) the large assortment of inappropriate members being offered by our code editor’s autocomplete.

Fortunately though, with a small team, we could communicate this risk and tip-toe around it while we iterated quickly on the new system.

After enough bumps and bruises, we finished up the last of the refactoring, resulting in two lines of business sharing the same codebase for things like payments, accounting, email notices, and entities common to both worlds of insurance.

Key Takeaways

You may find yourself in a situation like mine, but fear not, it is surmountable! Below are some high level key takeaways from this project.

1) Get your whole team on board so everyone knows what’s up and can share the decision.

Don’t put the burden entirely on your shoulders, even if you are most qualified to handle it. Keep everyone on the same page and unified by analyzing and sharing the various options. This project seemed a whole lot more intimidating when I was trying to tackle it all on my own.

When I brought my other team members into the picture, they were able to see things more realistically, rather than exclusively through my constricting developer perfectionism.

2) Benefit from the collective wisdom (books, articles, people).

In times like these, when you simply don’t know what to do and don’t feel confident, you can assume someone has encountered a similar problem and created a book or article about it.

In my case, I couldn’t find anything regarding whether or not it’s even a good idea to split up a large system in this way, so I had to go about asking real people their opinions. Combining that with the excellent refactoring books from folks like Fowler and Kierevsky, I was able to make gradual progress forward.

3) Understand and accept that you can’t always know if it will be the best decision until much later.

With large systems, it’s very hard to know if the path forward will end up fruitful without actually using it for some length of time.

Do your research, come up with a plan B and C in case it goes to hell quickly, and then march forward. Software is malleable and even with large decisions like these, you can work your way out if you have to.

Put your perfectionism aside and accept some amount of messy, unfinished business.

Is software ever really done anyway?

4) Remember that software is, by it’s nature, malleable. You always have the option of taking things in another direction.

Yes, it may be more difficult after some changes, but it’s not impossible. I found it was good to remind myself of this to help quell my fears and to keep moving forward. At any time if things started to look fishy, I could jump ship and branch the code into a separate app (I still could!).

Take your time and ideally do small releases so issues are caught fast.

Break the work up into small tasks and don’t worry about following patterns to the T, software can be a bit messy, especially very old systems.

5) Jump in and begin despite your fear.

I know it sounds a bit cheesy in the context of writing code, but you will ultimately have to just start. I had to accept that I wouldn’t be able to find a resource that laid out exactly what to do or told me if I was making the right move. I simply surrounded myself with the collective wisdom and then made tiny adjustments forward in a direction while communicating heavily with my team.

Refactoring can be done in small bits, it doesn’t have to be all at once. With our project, we went several months with half-divided quote classes that interfered with each other but were able to handle it because our team is small.

6) If you have a small team and a short_er_ deadline, consider sharing the existing system’s foundation.

Without a lot of team bandwidth or time on your side, you’ll want to lean on all your strengths and eliminate excess. By adding a line of business to your existing app, you’ll benefit from years of foundational code, bug fixes, and testing, and you’ll only have one application to deploy and manage.

7) If you have a large team and/or plenty of time, consider a new application or branched application.

With plenty of hands to spare or no impending deadline, you can benefit from the conveniences of modern technology. New platforms are great for shrinking dev and deployment time by reducing boilerplate code and being designed for easy cloud integration. If the new business line is unique enough, it may be worth building on a new foundation.

If you truly want to share existing features, you have the option of making them available via APIs or shared libraries. Just remember that the network is still the slowest part of a system.

God speed and good luck!

In part two I’ll share the tactical, code-level steps and order of execution that I used to make this line of business halving a manageable task.

My hope is that if you ever encounter this kind of problem you’ll be able to reference it to make it much easier rather than binging on architecture books like I did.

Escaping abstraction hell

Joe Petrakovich — Fri, 05 Jul 2019 00:00:00 +0000

You’re probably a lot like me when it comes to design decisions around code.

You like clean code.

It is satisfying to both read and write, your teammates appreciate it, and it makes your application easier to work with down line, so you put a lot of effort into it.

But upon the this purity of intent, the psychological gremlin of perfectionism often rears its head.

Driven by a subconscious shame and fear of failure, it’s becomes the obsession to find the best way to go about your task at hand.

It’s tough not knowing what you don’t know.

Of course, a quick web search to find the best way of doing something is a great thing, and it’s how our software improves, but what has happened to me, and likely you too, is that it becomes a worm hole.

Scanning one browser tab on how to use Mediatr then spawns three more on CQRS, keeping controllers thin, and the repository pattern.

You realize you weren’t following the single responsibility principle and that you have a command inside your query, so you’ll first need to refactor that.

As you refactor and are at the same time drinking beyond your fill from Google’s tit, you come across domain driven design and decide it would be better to host an event storming session with your team before you can feel comfortable implementing the original small task you were assigned.

This is a hell spiral.

It doesn’t end, and rather than finishing your task, you instead just add a bundle of abstractions that in theory reduce coupling, but are likely untimely and low in value to your team and your company.

This is usually because advice articles are written with a very specific problem context in mind which is often not your problem context, so you’re building your application based on the needs of some other application.

It’s also a lot like waterfall vs. agile software development.

The perfectionistic obsession has you putting the cart before the horse trying to predict eternity rather than just finishing your task.

The best architecture promotes agility (ease of change), but if you haven’t had a need to change anything about it, you’re prematurely optimizing based on a hunch.

What to do instead

First, don’t beat yourself up. This sort of architecture thrashing is something just about every developer I’ve ever met has done.

With time and experience, you will be able to make faster and better predictions for what kind of design a certain feature should have, but until then you can use a much simpler approach.

Start with just getting your feature working.

Put aside all of the shoulds the software world is tossing onto your shoulders and just get it working in the simplest way possible.

Perhaps begin with one single method and a set of comments that break the feature up into a high level algorithm.

 private void purchaseItem()
 {
     //set up payment gateway api client
     //process payment
     //generate receipt
 }

After you have it working, commit to maybe 30 minutes to an hour on basic tidying.

Focus this time on making it easy to understand (small methods, clear names), and on aiming for the single responsibility principal with your those methods and their classes.

That’s it.

Move the hell on.

And here is the important bit – you can trust that when your feature begins being used in the wild, the opportunity to iteratively improve the design will reveal itself organically.

Rather than toiling over upfront psychic predictions, your optimal design emerges via actual pain hot spots.

So you end up with a design that is more congruent with need, and you finish your features faster, with more ease and enjoyment.

Going further…

If this resonated with you, I encourage you to take a look at my article on boundaries to deepen your understanding of other personality traits that could be affecting your growth as a developer.

How To Refactor Business Logic Into Services

Joe Petrakovich — Sun, 23 Jun 2019 00:00:00 +0000

Yo dawg, are you controllers getting plump?

Well I’ve got one technique you can use to drop pounds QUICK!

What is one of the most common ways things start to chub up?

…

Business Logic.

Damn is it easy to slather on that biz logic fat right within our controller actions.

So what can we do about it?

Business Logic Thinning Strategies

There are multiple strategies you could choose to tackle business logic in a controller. Naming just two of them, you could:

Move the logic into reusable ActionFilters

Good if the logic is common amongst other controller actions like authorizing access to an entity. However, it does still couple the business logic with controller-related libraries. In other words, you wouldn’t use an ActionFilter outside of an MVC or API route, which would mean you couldn’t use that business logic outside of that domain either. Perhaps you never would anyway, so in that case, an ActionFilter might be a fine, pragmatic choice.

Move the logic into a service that is injected into the controller

This way works well because your business logic can live happily in its own reusable class, without coupling itself to any particular client technology.

This is the strategy we’ll be looking at for the remainder of this article.

Refactoring business logic into services

First, let’s clarify terms.

Business Logic

For our purposes, business logic is any code that implements the goals of the business. For an e-commerce application, this would be processes or tasks like creating orders, processing payments, creating and sending receipts, and adding or updating customer data.

In comparison, controllers are only responsible for managing the incoming HTTP request, delegating the work of satisfying the request, and passing on a response.

If you have trouble identifying the boundary between business logic and controller logic (clarifying responsibilities), send me a message on Twitter and I’ll try to help.

Services

A service is really anything that… serves.

Whenever you call a method on one class from another, the calling class is the client and the class with the method is the service.

So there you have it, a service is a class with a method that can be called.

Sticking our business logic in its own class has a number of advantages. The ability to use the feature in areas beyond just the controller, the ability to test the business logic (and the controller) in isolation, and a big improvement in readability due to the fact that a blob or blobs of logic filling the controller can be reduced to clearly named method calls.

The code in question

Ok, I’m going to throw you for a bit of a loop.

The code we will be refactoring is actually an Azure Function, and not a controller.

Don’t freak out. Let me explain.

I’m choosing to use this code because it’s actual real world production code rather than an invented example.

On top of that, the code used to build an Azure Function is so gosh darn similar to a controller that you would barely know the difference if I didn’t call it out.

There are minor differences that I’ll point out, but the refactoring concepts in this article can still be applied 1-to-1.

For that reason I’ll be using the word controller and function interchangeably for the remainder of this article.

Let’s see the code…

public static class HandleNotification
{  
    public static async Task<IActionResult> Run(
        HttpRequest req, 
        ILogger log, 
        ExecutionContext context)
    {
        log.LogInformation("C# HTTP trigger function processed a request.");

        var config = new ConfigurationBuilder()
            .SetBasePath(context.FunctionAppDirectory)
            .AddJsonFile("local.settings.json", optional: true, reloadOnChange: true)
            .AddEnvironmentVariables()
            .Build();

        var googleSheetsCredentialsPath = Path.Combine(context.FunctionAppDirectory, "credentials.json");

        var spreadsheetDefinition = (ID: config["SpreadsheetId"], Name: config["SpreadsheetName"], Range: config["SpreadsheetRange"]);

        var requestBody = await new StreamReader(req.Body).ReadToEndAsync();

        var googleSheetsService = GetGoogleSheetsService(googleSheetsCredentialsPath);

        log.LogInformation(requestBody);

        try
        {
            var jsonSerializerSettings = new JsonSerializerSettings { NullValueHandling = NullValueHandling.Ignore, ContractResolver = new DefaultContractResolver { NamingStrategy = new SnakeCaseNamingStrategy { } } };
            var samCartEvent = JsonConvert.DeserializeObject<SamCartEvent>(requestBody, jsonSerializerSettings);

            if (samCartEvent.Type == EventType.Order)
            {
                await AddOrderToSalesLogSpreadsheet(samCartEvent, spreadsheetDefinition, googleSheetsService);
            }
            else if (samCartEvent.Type == EventType.Refund)
            {
                await SetExistingOrderStatusToRefunded(samCartEvent, spreadsheetDefinition, googleSheetsService);
            }

            return new OkResult();
        }
        catch (Exception e)
        {
            log.LogError(e, e.Message);

            return new BadRequestObjectResult(e);
        }

    }

    private static async Task AddOrderToSalesLogSpreadsheet(SamCartEvent orderEvent, (string ID, string Name, string Range) spreadsheetDefinition, SheetsService sheetsService)
    {
        var customerName = $"{orderEvent.Customer.FirstName} {orderEvent.Customer?.LastName}";
        var programCity = orderEvent.Order.CustomFields?.SingleOrDefault(cf => cf.Name == "Program City")?.Value;

        var row = new List<object>() { orderEvent.Order.ID, customerName, orderEvent.Customer.Email, programCity, DateTime.Now.ToString("MM/dd/yyyy h:mm tt"), "Ordered" };

        var valueRange = new ValueRange();
        valueRange.Range = spreadsheetDefinition.Range;
        valueRange.Values = new List<IList<object>>();
        valueRange.Values.Add(row);

        var appendRequest = sheetsService.Spreadsheets.Values.Append(valueRange, spreadsheetDefinition.ID, spreadsheetDefinition.Range);
        appendRequest.ValueInputOption = SpreadsheetsResource.ValuesResource.AppendRequest.ValueInputOptionEnum.USERENTERED;

        var appendResponse = await appendRequest.ExecuteAsync();
    }

    private static async Task SetExistingOrderStatusToRefunded(SamCartEvent refundEvent, (string ID, string Name, string Range) spreadsheetDefinition, SheetsService sheetsService)
    {
        var refundedOrderID = refundEvent.Order.ID.ToString();

        var salesLogSpreadsheet = await sheetsService.Spreadsheets.Values.Get(spreadsheetDefinition.ID, spreadsheetDefinition.Range).ExecuteAsync();

        string statusCell = FindExistingOrderStatusCell(refundedOrderID, salesLogSpreadsheet, spreadsheetDefinition.Name);

        if (statusCell != null)
        {
            var row = new List<object>() { "Refunded" };

            var valueRange = new ValueRange();
            valueRange.Range = statusCell;
            valueRange.Values = new List<IList<object>>();
            valueRange.Values.Add(row);

            var updateRequest = sheetsService.Spreadsheets.Values.Update(valueRange, spreadsheetDefinition.ID, statusCell);
            updateRequest.ValueInputOption = SpreadsheetsResource.ValuesResource.UpdateRequest.ValueInputOptionEnum.USERENTERED;

            await updateRequest.ExecuteAsync();
        }

    }

    private static string FindExistingOrderStatusCell(string orderID, ValueRange salesLogSpreadsheet, string spreadsheetName)
    {
        string statusCell = null;

        for (int i = 0; i < salesLogSpreadsheet.Values?.Count; i++)
        {
            var row = salesLogSpreadsheet.Values[i];

            if ((string)row[0] == orderID)
            {
                statusCell = $"{spreadsheetName}!F{i+1}";
                break;
            }
        }

        return statusCell;
    }

    private static SheetsService GetGoogleSheetsService(string credentialsPath)
    {
        GoogleCredential credential;
        string[] _scopes = { SheetsService.Scope.Spreadsheets };

        using (var stream = new FileStream(credentialsPath, FileMode.Open, FileAccess.Read))
        {
            credential = GoogleCredential.FromStream(stream).CreateScoped(_scopes);
        }

        // Create Google Sheets API service.

        var sheetsService = new SheetsService(new BaseClientService.Initializer()
        {
            HttpClientInitializer = credential,
            ApplicationName = "SamCart Notification Listener"
        });

        return sheetsService;
    }
}

Comparing Azure Functions and ASP.NET Controllers

You’ll notice right away that this code comprises a single class with a single method that returns an IActionResult. Nearly identical to an action method endpoint of a Controller.

The main difference is that it is declared as static and passes a few arguments that you may not be used to (we’ll be changing that with our refactoring).

A brief explanation of behavior

This code is used as a listener for processing sales notifications that come from a shopping cart web app called SamCart.

You can configure an endpoint URL within SamCart’s admin panel that it will POST notifications to upon successful sales (or refunds). This code listens for those notifications and logs them to a Google Sheet spreadsheet using the Google Sheets API and it’s client library.

Tackling the task of refactoring

In an earlier article we looked at some strategies for code cleanup.

In this particular class, we have a fairly large Run method that is doing multiple logical blocks of work.

Can you name them?

…

Setting up configuration, reading and parsing the HTTP request body into a SamCartEvent POCO, and making use of the Google Sheets API to either add a new sales order or update the refund status of an existing order on a spreadsheet.

In order to simplify this code so that it’s easier to read and easier to change, let’s try to break it up into smaller bits and follow the Single Responsibility Principle more closely.

Parsing…

First, I found out the day of writing this article that Azure Functions allow you to benefit from the same automatic model binding that Controllers are provided. I was lead astray by the original template-generated code that you can see is manually parsing the HTTP request body.

So our first change is to completely eliminate that parsing logic and simply declare a SamCartEvent as the first argument to the Run method.

I’m also going to remove the logging calls and the logger argument for the clarity of this demonstration.

public static async Task<IActionResult> Run(
    SamCartEvent samCartEvent, 
    ExecutionContext context)
{
    var config = new ConfigurationBuilder()
        .SetBasePath(context.FunctionAppDirectory)
        .AddJsonFile("local.settings.json", optional: true, reloadOnChange: true)
        .AddEnvironmentVariables()
        .Build();

    var googleSheetsCredentialsPath = Path.Combine(context.FunctionAppDirectory, "credentials.json");

    var spreadsheetDefinition = (ID: config["SpreadsheetId"], Name: config["SpreadsheetName"], Range: config["SpreadsheetRange"]);

    var googleSheetsService = GetGoogleSheetsService(googleSheetsCredentialsPath);

    try
    {
        if (samCartEvent.Type == EventType.Order)
        {
            await AddOrderToSalesLogSpreadsheet(samCartEvent, spreadsheetDefinition, googleSheetsService);
        }
        else if (samCartEvent.Type == EventType.Refund)
        {
            await SetExistingOrderStatusToRefunded(samCartEvent, spreadsheetDefinition, googleSheetsService);
        }

        return new OkResult();
    }
    catch (Exception e)
    {
        return new BadRequestObjectResult(e);
    }       
}

With that cleaned up, we are left with only two primary tasks. Setting up configuration, and making use of the Google Sheets API.

Creating a service class

Looking a bit deeper, we see that the configuration is only used by the Google Sheets API, so we could say that the work involved in setting it up is really along the same logical block of work of calling the API’s various services.

For that reason, it makes sense to move all of that code into it’s own class to be used as a service.

To do that, I’ll create a new class and method, named after what this code is actually doing from a high level. Ultimately we are using Google Sheets to log our SamCart events to a spreadsheet, so we move all of that code behind a method called LogEvent for the class GoogleSheetsSamCartEventLogger.

One key difference here is that at the time of writing this article, there was no way to inject the ExecutionContext needed to derive the location of the configuration file, so the first line of code is an alternative way of doing so.

The rest is the same as before: getting the spreadsheet configuration and calling the appropriate API endpoint based on the type of SamCartEvent.

public class GoogleSheetsSamCartEventLogger
{
    public async Task LogEvent(SamCartEvent samCartEvent)
    {
        var functionAppDirectory = Environment.GetEnvironmentVariable("AzureWebJobsScriptRoot")
                ?? (Environment.GetEnvironmentVariable("HOME") == null
                    ? Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location)
                    : $"{Environment.GetEnvironmentVariable("HOME")}/site/wwwroot");

        var config = new ConfigurationBuilder()
            .SetBasePath(functionAppDirectory)
            .AddJsonFile("local.settings.json", optional: true, reloadOnChange: true)
            .AddEnvironmentVariables()
            .Build();

        var googleSheetsCredentialsPath = Path.Combine(functionAppDirectory, "credentials.json");
        var spreadsheetDefinition = (ID: config["SpreadsheetId"], Name: config["SpreadsheetName"], Range: config["SpreadsheetRange"]);
        var googleSheetsService = GetGoogleSheetsService(googleSheetsCredentialsPath);

        if (samCartEvent.Type == EventType.Order)
        {
            await AddOrderToSalesLogSpreadsheet(samCartEvent, spreadsheetDefinition, googleSheetsService);
        }
        else if (samCartEvent.Type == EventType.Refund)
        {
            await SetExistingOrderStatusToRefunded(samCartEvent, spreadsheetDefinition, googleSheetsService);
        }

    }

    private async Task AddOrderToSalesLogSpreadsheet(SamCartEvent orderEvent, (string ID, string Name, string Range) spreadsheetDefinition, SheetsService sheetsService)
    {
        //...

    }

    private async Task SetExistingOrderStatusToRefunded(SamCartEvent refundEvent, (string ID, string Name, string Range) spreadsheetDefinition, SheetsService sheetsService)
    {
        //...

    }

    private string FindExistingOrderStatusCell(string orderID, ValueRange salesLogSpreadsheet, string spreadsheetName)
    {
        //...

    }

    private SheetsService GetGoogleSheetsService(string credentialsPath)
    {
        //...

    }
}

With this service class created, we now just need to make use of it in our original Run method.

The fastest way to do that would be “new it up” directly in the method. Let’s go that route first, and then we will improve upon it further on in the article.

public async Task<IActionResult> Run(SamCartEvent samCartEvent)
{
    try
    {
        var eventLogger = new GoogleSheetsSamCartEventLogger();

        await eventLogger.LogEvent(samCartEvent);

        return new OkResult();
    }
    catch (Exception e)
    {
        return new BadRequestObjectResult(e);
    }
}

Now we are looking good.

We have a much thinner method with a lot less reasons to change (code stability). Our method simply needs to hand off the work to a service and respond with a relevant result.

It is now more likely that the event logger would change, rather than the function or controller itself.

Can we improve this code further?

Earlier we mentioned “newing up” the event logger. If we instead make use of dependency injection, we can move the responsibility of choice onto the application itself.

Responsibility of choice is a term I’m coining just now which entails the decision of how a certain behavior is implemented.

As it stands right now, we are hardcoding the use of Google Sheets by our listener. Meaning it would require an actual code change and redeployment to ever log our events differently. This could be perfectly fine if you had no plans or requirements to change your logging mechanism, but for the sake of demonstration, let’s say that our customer mentioned possibly wanting to move the logging to Microsoft’s Excel, or to a plain old text file.

With that being the case, it would be in our benefit to allow changing the implementation of event logging, without having to change the controller.

Less change = less risk.

This is where a combination of interfaces and dependency injection come in handy.

First, we can extract an interface from our Google Sheets event logger.

public interface ISamCartEventLogger
{
    Task LogEvent(SamCartEvent samCartEvent);
}

public class GoogleSheetsSamCartEventLogger : ISamCartEventLogger
{
    //...

}

With this in place, we are now free to create as many different logger implementations as we want.

As an example, we could have a very primitive console logger like this one.

public interface ISamCartEventLogger
{
    Task LogEvent(SamCartEvent samCartEvent);
}

public class ConsoleSamCartEventLogger : ISamCartEventLogger
{
    public async Task LogEvent(SamCartEvent samCartEvent) 
    {
        if (samCartEvent.Type == EventType.Order)
        {
            Console.WriteLine("An order was placed!");
        }
        else if (samCartEvent.Type == EventType.Refund)
        {
            Console.WriteLine("Aww... a refund.");
        }
    }
}

Interfaces are fun, but without dependency injection we would still have to change the code of the controller’s Run method to “new up” the alternative implementation.

Remember this?

public async Task<IActionResult> Run(SamCartEvent samCartEvent)
{
    try
    {
        var eventLogger = new ConsoleSamCartEventLogger();

        await eventLogger.LogEvent(samCartEvent);

        //...

    }
    //...

}

Let’s instead make use of the built in dependency injection container that is provided by ASP.NET to move the implementation decision to the application startup configuration.

To do that in an Azure Function is very similar to how you do that in an ASP.NET MVC or Web API project, you simply register your types in the Startup.cs class and then use them via constructor parameters.

public class Startup : FunctionsStartup
{
    public override void Configure(IFunctionsHostBuilder builder)
    {
        builder.Services.AddScoped<ISamCartEventLogger, GoogleSheetsSamCartEventLogger>();
    }
}

public class HandleNotification
{
    private readonly ISamCartEventLogger eventLogger;

    public HandleNotification(ISamCartEventLogger eventLogger)
    {
        this.eventLogger = eventLogger;
    }

    public async Task<IActionResult> Run(SamCartEvent samCartEvent)
    {
        try
        {
            await eventLogger.LogEvent(samCartEvent);
        }
        //...

    }
}

With it moved, we have improved the stability of the code by no longer needing to change the controller’s Run method.

We have also dramatically enhanced the readability of each individual component. Compare the above code snippet to the original code at the beginning of the article.

Azure Functions vs. AWS Lambdas: A .NET Developer's Perspective

Joe Petrakovich — Tue, 11 Jun 2019 00:00:00 +0000

Have you gotten around to trying this “serverless” stuff out?

I recently had to scratch my own itch and put together a couple small utilities, one with an AWS Lambda, and the other with an Azure Function.

Have you wondered if one was better than the other?

The experiences were… similar, but also quite different, and thus I share a .NET developer’s perspective of each.

Before I start, keep in mind that whilst building both of these utilities, my mindset was “let’s get this thing live as fast as possible”, and not “let’s do precision research on the most effective way to implement this using each platforms recommended tooling and workflow”.

Nowadays I tend to try and get something working first, and then refactor it into something more elegant after.

With that in mind, this article reflects my opinion as a first time user just getting started, with a bias of being heavily engulfed in the .NET world and with quite a bit of prior Azure experience (I’ve built out an entire Azure cloud infrastructure from scratch.)

In contrast this was the first time touching AWS other than migrating personal files from Dropbox to an S3 bucket (easy way to save 10 bucks a month!)

Building an AWS Lambda

The idea of using an AWS Lambda came to me when I was stubbornly resistant to putting any javascript on this very blog. Not because I don’t like javascript, but simply because the blog started out as pure static html and css and the minimalist in me wanted to keep it that way.

I needed an elegant way to allow folks on my email list to be able to sign up for other gizmos on my site even if they had already signed up for something else.

My email provider, Mailchimp, would require you to check off boxes for what they wanted, which was a shit experience.

I could have called their API via some javascript, but rather than shattering my holy static site purism, I decided to have my email sign-up form simply POST itself and handle the work on a server. Since I had recently deallocated my personal server droplet, I thought hey, a serverless function would be perfect!

Being the first time I dipped my toes into serverless, I found the experience very liberating.

Once you create an AWS developer account and navigate around the grid of seemingly hundreds of oddly named AWS resource offerings displayed in Amazon’s classic ugly font against a dull gray background, it’s fairly seamless setting up a basic Lambda.

The Lambda creation workflow guides you along choosing a language and platform, sets you up with an in-browser text editor, and presents an interface similar to one of those middle school programming languages where you link different components together for input and output.

It’s ugly, and it gets more confusing as you add additional complexities, but it works.

For this project, I chose NodeJS as the framework, since I had recently enjoyed how its expansive package ecosystem paired with javascript’s loose typing allowed me to fumble together guilt-free utilities at lightning speed.

Now, I’m willing to bet there are nicer deployment experiences than what I used, but combining NodeJS with the in-browser editor was not ideal.

If you haven’t used NodeJS before, when you want to pull in an outside library like you would with NuGet in the .NET world, you have to declare its use first and then npm (the package manager) pulls in all of the library’s raw code right within your project into a folder called node_modules.

This process is mostly automatic if you have your local dev environment set up for it, but it doesn’t work in the AWS Lambda in-browser editor. The only solution at the time of building it was to instead build the majority of the utility locally using VS Code, then uploading it and the node_modules folder back into AWS.

Like I said, there are probably better ways, but this was my experience trying to build at relatively fast pace.

Once I had the utility doing what I needed, which was essentially just calling a few Mailchimp API endpoints, I just had to configure the function so it could actually be executed via an HTTP POST.

You can see the code here if you’re curious. It ain’t perfect but it gets the job done!

This was another knock against AWS. Although I will say, it was still a good experience, but you’ll see why I say this when we get to the Azure side of things.

In order to set up the endpoint, you had to provision another kind of AWS resource called an API Gateway.

An API Gateway allows you to set up the URL format, authentication scheme, and available HTTP methods that you can slap in front of any other AWS resource as the first line of interaction from the public internet into your cloud resources.

Still easy in the grande scheme of software development and deployment, but again, Amazon could definitely work on the user experience design.

I did have some difficulty creating an authorization scheme so that only my website could call it. Compared to Azure Functions, it was rather confusing to set up a token that could be used. Eventually I figured it out, but it’s worth noting that it wasn’t seamless.

Once the API Gateway was up and running, I was good to go.

At the time of this article being written, this Lambda has been serving this site without any errors for several months at no cost to me.

Despite the quirks with uploading javascript files and vanilla Amazon design, I found this to be very gratifying.

Both AWS and Azure offer these services with 1 million free executions per month, so if you’re creating something with less traffic than that, it’s pretty amazing to be able to plug into that computational power for almost no cost.

Pros

Integrates well with other AWS offerings.

If you’re already an AWS user, you might as well stay within the confines. Lambdas are built with the expectation that you will connect them to your other AWS resources, and from my experience, both AWS and Azure are similar enough that there wouldn’t be a compelling reason to exit your existing cloud.

If you prefer command-line tooling, or are a linux/java dev, you might enjoy AWS Lamdas more.

I believe Amazon skimps on their UI because they offer robust command-line tooling. I’ve only used a bit of it in my experience, but have heard from others that it is great. I encourage you to explore that on your own and report back.

Cons

The user experience is lacking.

I find Amazon to be lacking in design in just about ALL of their products. Maybe it’s just me but I find myself wondering how anyone can navigate around their sites if they aren’t already a keen technologist. But hey, money bags Bezos obviously isn’t hurting from it.

Setting up the API Gateway was clunky.

This was similar to above, a user experience problem. A bit confusing setting up an authorization scheme.

Manually uploading the source files wasn’t pleasant.

It’s likely AWS has a better deployment method, but this was the straightforward solution using the in-browser editor.

For all I know, there might be Visual Studio tooling that would have made it easier, but again, it wasn’t obvious, and you’ll see below how drastically different this experience was whilst already being in the Microsoft landscape as a .NET developer.

Azure Functions

My introduction to Azure Functions was very recent, about one week before writing this article, so it’s fresh on my mind.

A friend of mine uses a shopping cart tool that doesn’t provide a public API to its users, but instead offers a push notification event option. So you can’t them ask “how many sales have I made for this product?”, but you can listen for sales events, collect that data into your own database, and then you’ll be able to answer that question for yourself.

Handling notifications from an external service is a perfect use case for a serverless utility, so this was my hell yes moment. Time to try out new toys!

I had two big advantages coming into this, one that I had already used Lambdas, and two, that I have essentially built an Azure cloud infrastructure from the ground up, so it was all familiar territory. First I followed the Getting Started documentation to familiarize myself with the Portal based deployment which is analogous to the AWS in-browser text editor.

What I noticed right away, to contrast from AWS, is that two of the main trouble spots I had with AWS were taken care of by default in Azure. Simply selecting the Webhook + API function template option from the initial wizard automatically created the API endpoint for calling the function, along with a client authentication token.

In the prior step you could also choose from a number of deployment methods including Visual Studio, VS Code, Portal editor, and command-line.

Because the functionality of this utility was going to be rather complex (parsing an incoming notification and calling the Google Spreadsheets API to fill a table), I decided to try out the Visual Studio deployment option rather than the browser editor.

For this, I upgraded Visual Studio 2017 to 2019 (yay more new toys!) and used the included template for an Azure Function.

This was dope.

It sets you up with a local dev environment to test on, and get access to the usual one-click publishing feature that lets you push everything right into Azure. One thing that stood out to me as pretty nifty was the local to remote app settings UI.

Your app settings are encrypted locally, and when deployed, you could see a side-by-side comparison of local vs. remote settings values where you could edit right within Visual Studio.

It should be expected, really, but this is where it helps to already be a .NET and Visual Studio user. The experience of building this (in .NET Core by the way), testing it, and deploying it was seamless. All the way from finding up-to-date documentation and guides, to having a live function that processes those shopping cart events.

It was also nice that the function itself was very similar to an ASP.NET Core controller action.

Pros

As a .NET Developer, Azure’s integration with Visual Studio made the entire experience far more delightful.

You can choose to build and deploy from the Azure Portal, Visual Studio, VS Code, or command line, and each option came with clear documentation and easy publishing steps.

HTTP trigger endpoints and authentication configured by default, stupidly easy.

The most common ways you will want to set up your function are configured by default. There aren’t additional resources you need to learn about or set up.

Strong documentation

Microsoft has been putting a ton of effort in to create clear and up-to-date documentation and the effort is obvious in this area.

Cons

I’m reaching here, but if I were to knock something it would be that sometimes it’s not clear what things cost.

For example, I understood that 1-million executions of the function would be free, but in order to have the function live, you also need a storage account. It might be nice to display dollar values in-and-around the deployment screens.

Both Visual Studio and Azure Portal do a nice job at auto-populating everything you need, so it would be cool if it also made it clear what the total monthly cost estimate is. I noticed that my current Azure storage account and logging resource will bill me about $0.12 per month as it currently stands.

Final Thoughts

Coming from my current job where we are still deploying manually via installer UIs on virtual machines, this whole experience with serverless functions was an incredible delight. That’s with both AWS and Azure.

It brought me back to that classic experience of my childhood when I got boosts of self-esteem from writing a bit of HTML and CSS and seeing it magically create something in the browser instantly. This was that experience all over again except with actual computation on a live HTTP endpoint over the web.

The fact that we can build these micro apps at little to no cost is also a real game-changer, especially as an entrepreneur. It opens up an entirely new canvas to create upon.

I encourage you to try both AWS Lamdbas and Azure Functions, since I found them to be similar enough that your own personal preferences will be more important than my opinion. With that said, I believe you will find a much more seamless and fluid experience by using Visual Studio with Azure Functions. All the futzing around I had to do with AWS was taken care of by default in Azure.

As you might expect, it’s a lot like using a Mac if you are an iPhone user. You benefit greatly by staying within the walls of your ecosystem.

Practical Visual Studio Tips Part 1

Joe Petrakovich — Thu, 25 Apr 2019 00:00:00 +0000

One of the best ways to become a solid, more productive and effective developer is to really master the things you do most often.

The kickoff article that initiated this practical Visual Studio tips series highlighted the extract method refactoring (my absolute favorite) and how we can harness Visual Studio’s keyboard shortcuts like a Dothraki warrior so that we can write code fast (if we want to), while improving readability.

For this next part in the series, we’ll take a look at two more shortcuts that you can use on a daily basis to speed up your workflow. Now, these particular shortcuts are rather basic, obvious even, but by giving them focus here and practicing them, you’ll use them more consistently and integrate them into a daily habit.

We humans are funny, or at least I am, anyway.

I’ll do the same thing over and over, and even after learning a faster way to do it, I’ll continue doing it my old way anyway simply because that’s the groove currently patterned in my brain.

The purpose of this article and often many of my articles are to give old patterns a second look so we can question our behaviors and change if necessary.

Tab + arrow key suggestion invocations

For the first one, we’ll go reaaaal primitive, but I’ll add a twist, so stick with me.

When you’re writing code in Visual Studio, a program called Intellisense is actively analyzing each character you type and trying to determine what you might be trying to write.

Typing is slow, so if the editor can predict what you are about to write with accuracy, you can lean on it to reduce the number of keystrokes you have to make.

It’s here to make our lives easier!

On top of that I’ve found that Intellisense is pretty damn smart, and either suggests exactly what I want right away, or the option I want is one or two list items up or down.

Pay particular attention below at how I can type these extra long statements in about half the number of keystrokes compared to typing each letter manually.

What I want for you is to get used to either hitting the tab key to invoke the suggestion, or using the arrow keys on your keyboard to select the desired option in the Intellisense dropdown menu, then hitting tab or enter to invoke it.

Type only the first few characters and let your eyes pinpoint the correct suggestion as it appears.

Start to relax and trust that what you want will be available and lean on Intellisense to improve your productivity and make you seem like a developer wizard to your friends and teammates.

Funny side note, I’ve actually had two past lovers comment “Damn, that’s really hot” when I’m dishing out commands to the console.

Who would have thought, skill and proficiency is sexy!

Master your editor and keyboard.

Renaming like a savage

Alright, now you’re going about your day, shrinking big methods via extract method, leaning on Intellisense predictions so you can type less, what else can we do to pro it up?

Another very common thing you probably do as a compassionate and considerate dev, is constantly refine your names.

The longer you work on a codebase, the better your understanding of it, which leads to clearer, more accurate class, method, property, and variable names.

I rename all the time. Often I’ll come up with one name at the start of a method, then after actually implementing the method, I’ll realize it could be named in a way that conveys it’s intent even better.

For that reason, making the process of renaming as fast as possible is another worthy endeavor.

Fortunately for us, it has a built-in keyboard shortcut, so we only have to understand how to use it, and to remember it.

The first act in a renaming is to select the entire existing name you’d like to change.

To do that, the best way I’ve found is to use your mouse or trackpad and double-click the word itself.

Visual Studio understands logical delimiters of a name in code and will automatically highlight the word.

Once highlighted, hold down the CTRL key, then quickly hit the letter R twice.

Once the rename refactoring is invoked, you can begin typing your new name at once and notice it changing across all usages.

And there you have it.

Get used to trusting intellisense, and speed up your renames.

In the next article in the series, we’ll either continue mastering common tasks, or I may go for something new that peaks my interest… I haven’t quiiiite decided.

Stay tuned!

Perfectionism

Joe Petrakovich — Tue, 09 Apr 2019 00:00:00 +0000

When I was younger, I used to think perfectionism was a good thing.

The word “perfect” is in it, after all.

But I never thought I was a perfectionist. I only had heard other people say it about themselves, wearing the term like a badge of honor.

“Oh, it’s just because I’m a perfectionist” someone would exclaim, after they had just created something utterly amazing.

So in my mind, it meant striving for the utmost. Doing your absolute best work.

I surely wasn’t one of those, I thought. I just did what felt normal to me. The standard I set for myself is what I’d always known, so I wasn’t aware that it was actually a struggle. That I was actually draining myself to the point of burn out, disguised as just being very thorough.

It wasn’t until later in my career did I realize the plague that perfectionism really is, and that I had been stuck in it for most of my life without even realizing it.

The experience of perfectionism for me is a ruthless attempt at control and a nagging anxiety when something threatens that control. It’s also like turning up the volume knob on your focus and attention to detail. You take in every last drop of information (to reduce the risk of doing something wrong).

If you’re like me, you’ve likely been doing this your whole life.

If you’ve ever worked on some kind of feature at your job, taking 100% ownership of it, and then felt triggered by another developer “stepping into your territory”, it’s likely you have a similar issue with control and perfectionism.

When I sit with it, I can see it really comes from fear.

Fear that something will go terribly wrong. You may not have realized it at the time, but you put so much intensity and focus on getting it right all on your own, that the idea of someone else stepping on your perfect sand castle brings you into turmoil.

One of the things I’m having to learn though, is that you can’t do it all on your own.

You can try, but you can only get so far, and you’ll eventually burn out.

It’s a success barrier.

When you work on a team, you have to develop trust in others, and you have to be okay with differences in skill, interpretation, attention to detail, and style.

You have to be able to share the workload and let things go.

If you’re like me, you’ve likely grown up thinking you’re all on your own. Thinking you can only depend on yourself. That no one else will help you, so ya might as well become superhuman and figure it out alone.

If you don’t become aware of this pattern, you will continue to burn yourself out over and over and over.

You don’t have to do it all on your own.

Breathe.

Let your teammates learn some things on their own. Give them the opportunity to try and succeed or try and fail.

Now, looking at it another way, learning how to be okay with some amount of uncertainty and mess is something to continually work on, but so is acceptance of who you currently are.

Despite it being born out of necessity as a child, your attention to detail is certainly a powerful advantage, so don’t be ashamed of it.

I sometimes catch myself feeling like the controlling tyrant when my precise awareness has me wagging my finger at my less detailed cohorts.

Of course, you don’t want to be judging others as if they are less than, but it is absolutely 100% okay and valid to express your concern and opinion based on your hyper-detailed experience.

There’s a dichotomy at play.

Be okay with some amount of mess, the human variance, yet don’t be afraid to use your advantage to maintain order and prevent the always impending chaos.

Orderliness and attention to detail are powerful strengths, yet when they sink into anxiety from loss of control, it becomes perfectionism, and perfectionism controls YOU.

Learn the difference.

Going further…

If this resonated with you, I encourage you to take a look at my article on boundaries to deepen your understanding of other personality traits that could be affecting your growth as a person and as a developer.

The fastest way to sexy code using Visual Studio

Joe Petrakovich — Fri, 22 Mar 2019 00:00:00 +0000

Here it comes.

Another spicy new update to Visual Studio.

And yet, it’ll come and go and I’ll most likely continue using the same damn subset of features I’ve gotten used to for years.

Same as you, right?

Code highlighting, Find By References, and Go To Declaration. A glorified text editor with enhanced file search.

It takes time and deliberate effort to learn a new feature, let alone implement it regularly enough that its true value is realized.

Time we just DON’T have.

Which sucks because there are treasure troves of wizardy hidden beneath Visual Studio’s hefty mass that could improve our code, our software overall, and make us better devs in the process.

But there is one feature that you don’t have to look too deep to find.

One that will massively boost the quality of your code.

In this article I want to share with you not only the Extract Method refactoring feature, but also how to perform it at lightspeed, and how to use it most effectively, hopefully resulting in a surge of brilliantly clear code from your fingertips and immense gratitude from your teammates and future developers.

Did I sell ya on it?

Readability: an aside

Before we jump in to the technicals, let’s back it up with a bit of context.

Code readability is a human factor.

We strive to make our code as readable as possible, often over all other considerations, so that the next developer (which could be you) has the best possible chance of understanding what it does and what you intended.

Despite code being the literal manifestation of pure logic, it is still an exhausting endeavor for any human to decypher for too long.

For that, we compose our code to be more like prose in a book.

Its algorithms, object interactions, and architectures ideally can be read aloud to a senior dev, an intern, and a business analyst, making up a coherent ubiquitous language, as they say in the DDD world.

With this in mind, I believe liberal use of clearly named methods is the easiest way to improve readability in our codebases.

Clearly named methods can be added both at the time of development, or during refactoring.

I often like to write an algorithm first, then decide after how it will be composed and named.

This is where the extract method refactoring joins the party.

The way of the sloth

The extract method refactoring simply means moving a block of code into a new method, and then calling that method from the original location.

Replacing code with a method.

Now, you could do this manually by creating a new method, highlighting, copying, and pasting the code block into that method, then deleting that original block and replacing it with the method call.

It was exhausting just typing that…

Below we can see that strategy in action on a particularly chubby method that binds a view model representing a quote for a loan to the fields of a web page.

Don’t feel bad if you still do it this way. It’s tried and true. I did it this way for the first 7 years of my dev career.

The slightly faster, mouse-clicker strategy

The next bump in skillset comes when you realize Visual Studio has built in refactoring tools that make extracting methods a lot faster.

You can find the extract method shortcut three different ways: first by highlighting a block of code, then either waiting for that little yellow lightbulb (or blue screwdriver) icon to pop up and clicking it, right-clicking inside the highlighted region and selecting “Quick Actions and Refactorings”, or clicking CTRL+. to summon the suggestions manually.

Below you can see me demonstrating the right-click strategy.

Yep, juuuuust fast enough to let me demo two method extractions instead of one!

Now let’s go one final step to mastery.

The way of the superior developer

The final step to take us to light-speed, boss-ass bitch mode is to map the extract method feature to a keyboard command so you can finger-flick your way to readable code in under a second.

To do that, (open up VS and do it right now), go to Tools -> Options -> Environment -> Keyboard.

Filter the commands by typing “extract” and selecting the Refactor.ExtractMethod command.

Selecting “Text Editor” in the Use new shortcut in dropdown so that the command only applies when the text editor is in context.

And finally, typing the key command you’d like to use and selecting the Assign button and clicking OK.

You’ll want to choose a command that is easy for you to type quickly and comfortably (so that you remember it and use it.) I type using the Dvorak keyboard layout, so CTRL+; is the same as typing CTRL+Z on QWERTY, making it a quick flick of my pinky and ring finger.

Once that’s in place, try it out! And practice it so you don’t forget it.

Oops, went so lightning quick I misspelled producer!

Now, I have to say, it’s not wise to go this fast, but you get my point. The faster you can perform something, the more likely it is that you’ll use it.

Okay, now we’re playing pro level, but how can we use this new skill most effectively?

What I mean when I say liberal use

To close up, I’ll leave you with a few tips for improving the readability of your code.

1) Don’t be shy.

I would almost go as far as saying you can’t have too many methods. Readability > method count in my book.

On occasion , I will leave a method somewhat big instead of breaking it into several smaller methods, usually because I determined that seeing all of the logic on the screen at once was more comforting and allowed better reasoning, but this is a rare occasion.

You can even be as bold as to convert a single line of code into a method call if the method’s name is easier to understand than the statement alone. This works especially well with multi-conditional branching statements.

For example, what reads better?

This?

if (vehicles.Sum(v => v.Price) < loan.AmountRequested && Settings.IsExcessFundingAllowed)
{
    //fund excess amount...
}

Or This?

if (IsLoanFundingExcessAmount)
{
  //...
}

Methods also give you the opportunity to speak in the language of the business. The second example is easily understandable to all parties, whereas the first example needs a few more mental clock cycles to parse and understand, even by a developer.

The easier it is to understand, the easier it is to change in the future.

2) Pay attention to blank spaces.

Whenever I add a blank space, it’s usually to signify a new grouping of logic, just like paragraphs in an article.

Often times you can replace that grouping with a single method call that reads better than the grouping does in its raw state. The example in the animated GIFs above show this idea in action.

3) Create composed methods as a first line of defense

Notice in the example above how we composed a large method into several smaller ones. This is called the composed method refactoring, and it’s a great way to bring greater understanding to an algorithm or class. It’s much easier to understand a small bundle of clearly named methods than a blob of seemingly random statements.

It’s kind of like pruning a tree or picking weeds. Keep methods from growing in size by composing them into smaller ones as soon as it makes sense.

Practice, practice, practice

Alright, new skill in your pocket, now all ya gotta do is use it a few times until it that finger flick becomes muscle memory.

The extract method refactoring feature is easily one of my top three favorite and most used features, so I hope it brings some value to you and your team.

If you found this helpful, I’m going to be creating one new practical Visual Studio tip per month for the next 6 months.

It’ll be a mix of old (yet hidden) tools and brand spanking new tools, but only things I actually use regularly. If you’d like to skill-up with more power tools like this one, join my list below and I’ll email them to you as they come out, along with two to three other emails per month on related helpful articles and essays.

Hop over to the original article site to sign-up.

Visualizing thin ASP.NET Controllers via SOLID Principles

Joe Petrakovich — Mon, 11 Mar 2019 00:00:00 +0000

You can explain a code smell like fat controllers until you’re blue in the face, but some things just click better with pictures.

And to celebrate the newly available Thin Controller Recipes, I’d like to examine a particularly troubling issue for many .NET developers.

“I just don’t get the point of moving business logic from controllers into services…”

If it isn’t clear why you could benefit from biz-logic-free controllers, you may be missing some software design fundamentals that could make a boatload more sense after you read this article.

With that said, if the gurus are gonna preach the almighty state of thin controller-hood, we first have to understand why a fat controller is a code smell, what thin really means, and why it benefits us.

And, since thin is a relative adjective, we’ll use pictures (and some animated GIFs, woo!) to convey it.

Fat Controllers

Before I bust out my trusty Microsoft Pen, let’s look at some code so you can mentally map it to the pictures (and vice-versa).

Below is a theoretical controller for a bank loan application. This one processes requests for loans by calculating loan terms based on a the requested dollar amount and a person’s credit score.

public class LoanController : Controller
{
    private ILoanQuoteRepository _loanQuoteRepository;

    public LoanController(ILoanQuoteRepository repository)
    {
        _loanQuoteRepository = repository;
    }

    [HttpPost, Route("api/loans/quotes/")]
    public IActionResult CreateLoanQuote(LoanQuoteRequest request)
    {
        var quote = new LoanQuote(request.Amount, request.CreditScore);

        quote.CalculateLoanTerms();

        _loanQuoteRepository.SaveQuote(quote); 

        var response = new LoanQuoteResponse();
        response.Amount = quote.Amount;
        response.RequestStatus = quote.Decision;
        response.InterestRate = quote.InterestRate;

        return Ok(response);
    }
}

So, we start out with all of the logic implementing the quote creation business process inside the controller’s action method.

This is fat.

But it’s not fat in a vacuum, it’s fat relative to what it could be if SOLID principles were applied.

To be honest, the above controller is pretty tame, but the thing about business logic in the controller is, it encourages even more as time goes on. On a pinch, you or the next developer that needs to add some feature along the same code path will stick it riiight there. As will the next, and the next, and the next.

I don’t care for UML diagrams, and these soft pastels seem to cure my winter blues…

And just so we’re on the same page, purple represents the Controller class, green represents a controller action method, and the reddish-salmon color represents the logic.

Pay particular attention to the green actions as they are the best visual indicator of controller thickness (although the existence of other non-action methods in your controllers could also be a code-smell.)

So, why is this a code smell?

The definition of good code seems to change with the times. What was a good strategy 10 or 20 years ago is no longer as important today.

Today the focus is on flexibility.

Our software changes rapidly, so good code is code that is easy to change and code that is not so easy to break.

I can think of a several reasons code starts to smell around the fatness of the above controller:

1) There are many reasons it may need to change with actual code edits.

The controller is now the client of the repository, the request and response DTOs, and the LoanQuote domain entity, so if any of those change, it could percolate up and require the controller to change.

Change isn’t bad, of course, but it is risky. Can it be written in a way that is less risky? More testable, for example, or easier to understand?

2) You can’t test the controller in isolation.

To test the controller, you’d also have to test the LoanQuote’s CalculateLoanTerms() method.

3) The inclusion of domain logic invites the addition of more locally relevant logic by you and other developers.

I touched on this earlier. Big methods encourage laziness, and thus, even bigger methods.

Have you ever had to try and wrap your head around a behemoth method or a god object.

It ain’t fun.

4) Code inside a controller isn’t easily reusable.

I’ve changed my stance a bit on reusability, where I used to think it was a great thing to strive for in all cases, now – not so much. But, fat controllers do hint at the possibility that you’ve got logic for some process that you’ll have to write in multiple places.

Since controllers sit at the barrier between the user and the domain, and often applications have more than one way of executing the same task, you risk having duplication across each entry path.

What can we do about it?

This is where SOLID principles come in.

SOLID principles arose as a set of ideals that we can aim for to keep code adaptive and flexible.

The mantra “controllers should be thin” is actually a beckoning to abide to several SOLID principles in the context of a controller to fight against the issues I mentioned above.

It should be “Yo dawg, your controllers are doing TOO MUCH!”

In this case, we can benefit from the S , the O , and the D.

Thin Controllers via The Single Responsibility Principle

The Single Responsibility Principle (SRP) states that components should ideally only have one reason to change.

By shrinking the scope of an object’s duty, you compartmentalize behavior so that it is easier to reason about (making future changes easier), and you make it more stable because it shouldn’t need to be modified unless there is a feature or bug that involves that single responsibility.

When you have a controller with multiple responsibilities like in our example (mapping requests, responses, handling the quote entity and the repository), you have a large potential change surface.

I’ve used flashing red and green blocks to indicate areas of change. Green being code additions and red being existing code modifications or deletions.

How can we improve upon this design so that it isn’t so inviting to entropy?

Shrinking the controller’s change surface with application services

One immediate strategy is to simply move the logic that orchestrates the work between the DTOs and the LoanQuote into what is typically called an application service.

An application service can then be assigned the single responsibility of that task’s orchestration, leaving the controller to be a simple gateway between the HTTP request the service method.

You’ll notice a few things:

1) The controller (via the green action) is visibly thinner by a applying a better separation of concerns. That means the controller itself will be easier to reason about, and it won’t need to change as often.

2) We now have two objects instead of one. That does increase complexity, so there is a trade-off.

3) We’ve merely shoveled the girth of the controller somewhere else. Later you’ll see how application services can suffer the same problem of bloat as our controllers.

In code, we’ll create a service class that looks a lot like the original controller.

public class LoanService
{
    private ILoanQuoteRepository _loanQuoteRepository;

    public LoanService(ILoanQuoteRepository repository)
    {
        _loanQuoteRepository = repository;
    }

    public LoanQuoteResponse CreateQuote(decimal amount, int creditScore)
    {
        var quote = new LoanQuote(amount, creditScore);

        quote.CalculateLoanTerms();

        _loanQuoteRepository.SaveQuote(quote);

        var response = new LoanQuoteResponse();
        response.Amount = quote.Amount;
        response.RequestStatus = quote.Decision;
        response.InterestRate = quote.InterestRate;

        return response;
    }
}

And then shrink the controller down by merely delegating its old work to the new service.

public class LoanController : Controller
{
    private LoanService _loanService;

    public LoanController(LoanService loanService)
    {
        _loanService = loanService;
    }

    [HttpPost, Route("api/loans/quotes/")]
    public IActionResult CreateLoanQuote(LoanQuoteRequest request)
    {
        var loanQuoteResponse = _loanService.CreateQuote(request.Amount, request.CreditScore);

        return Ok(response);
    }
}

So, this is better, but can we add some flex to this design?

Programming to interfaces to support extension and further reduce the change surface

When creating application services, it is my preference to hide the implementation behind an interface to allow for easier testing, for extension via decorators, and to make my intention of loose coupling as clear as possible.

I started to animate the implementations overlaying the interface but it ended up looking like a whole lotta controller debauchery…

An interesting observation about this design is that, provided the interface’s method signature stays the same, your change surface is reduced to the injection point. In theory you’d only ever have to add new implementations or extensions rather than modify old ones.

I can’t say if it plays out that way very often in the real world, but it is a good example of the Open/Closed SOLID Principle.

Your controller can now stay unchanged, while your application service can be extended via decorators or simply swapped out entirely, all managed within your dependency injection container’s configuration site.

The interface:

public interface ILoanService
{
    LoanQuoteResponse CreateQuote(decimal amount, int creditScore);
}

The service simply implements the interface.

public class LoanService : ILoanService
{
   //...
}

And the controller specifies the interface for injection instead of the concrete implementation.

public class LoanController : Controller
{
    private ILoanService _loanService;

    public LoanController(ILoanService loanService)
    {
        _loanService = loanService;
    }

    //...
}

A drawback is that you do add complexity via more things to manage by creating an interface that only has one implementation.

A popular software engineering tenet is to program to abstractions, not implementations, but if we blindly put everything behind an interface, are we always better off? Some argue that if you find you do need the benefits of an interface, than you can always create one at that point in time.

I think that’s fair, but I sometimes will still work behind one to make my intent clear.

Okay, now that we have our task delegated behind an interface, we’ve got a much more flexible and modular design. The class responsibilities are better defined, and we’ve provided for extension points and we’ve decoupled the service implementation from the controller.

Is this all good, or can it sour?

Bloated application services

I mentioned above that application services can also bloat.

Instead of fat controllers, we get fat application layers.

I’d say the latter is better than the former simply because the responsibilities are clearer, but this outcome is most likely a result of the application service doing too many things.

The reality of controllers is usually far different than the simple single action controller that I showed at the start. We usually have at least a few actions, and each has potential to bloat.

Remember, the size of the green actions are the indication of fat. Disregard the purple controller class wrapping.

As you can see, once you’ve got a nice cozy home for that original orchestration logic, the tendency is to throw everything in there to satisfy all the work your controller needs to execute.

public class LoanController : Controller
{
    private ILoanService _loanService;

    public LoanController(ILoanService loanService)
    {
        _loanService = loanService;
    }

    [HttpGet, Route("api/loans/quotes/{id}")]
    public IActionResult GetQuote(int id)
    {
        var quote = _loanService.GetExistingQuote(id);

        return Ok(quote);
    }

    [HttpPost, Route("api/loans/quotes/")]
    public IActionResult CreateLoanQuote(LoanQuoteRequest request)
    {
        var loanQuoteResponse = _loanService.CreateQuote(request.Amount, request.CreditScore);

        return Ok(response);
    }

    [HttpPost, Route("api/loans/quotes/{id}")]
    public IActionResult DeleteQuote(int id)
    {
        _loanService.DeleteQuote(id);

        return NoContent();
    }
}

And the application service, handling it all:

public class LoanService : ILoanService
{
    private ILoanQuoteRepository _loanQuoteRepository;

    public LoanService(ILoanQuoteRepository repository)
    {
        _loanQuoteRepository = repository;
    }

    public LoanQuoteResponse GetExistingQuote(int quoteId)
    {
        var quote = _loanQuoteRepository.GetByID(quoteId);

        var response = new LoanQuoteResponse();
        response.Amount = quote.Amount;
        response.RequestStatus = quote.Decision;
        response.InterestRate = quote.InterestRate;

        return response;
    }

    public LoanQuoteResponse CreateQuote(decimal amount, int creditScore)
    {
        var quote = new LoanQuote(amount, creditScore);

        quote.CalculateLoanTerms();

        _loanQuoteRepository.SaveQuote(quote);

        var response = new LoanQuoteResponse();
        response.Amount = quote.Amount;
        response.RequestStatus = quote.Decision;
        response.InterestRate = quote.InterestRate;

        return response;
    }

    public void DeleteQuote(int quoteId)
    {
        _loanQuoteRepository.Delete(quoteId);
    }
}

When your application service has this many responsibilities, the benefits of putting it behind an interface are surely reduced.

Rarely would you decorate a single method on something that big, and swapping it out would be pretty unlikely too, as you’d need a reason to re-implement every method.

What can we do about this?

Breaking up fat application services via CQRS

A good solution to these fat service layers is to again apply the single responsibility principle and break them up into several smaller, single purpose classes.

A popular strategy that follows from that is command query responsibility segregation (CQRS).

Simplest way to explain it is that logic related to querying (database SELECT’s, really) is separated from logic that modifies (database UPDATE’s, INSERT’s, and DELETE’s)

Consider how most standard language APIs differentiate between the Reader’s and Writer’s when it comes to I/O. By keeping these tasks separate they are easier to reason about and modify and they won’t contain code that interferes with the other.

A very common trend I am seeing with CQRS is to use Jimmy Bogard’s Mediatr library and create small query and command classes that are propagated through an execution pipeline.

This article from Jimmy himself shows that technique.

I’ve yet to get my hands dirty with Mediatr, so I will instead discuss a simplified way of implementing CQRS.

Keeping CQRS simple just means keeping the query and command codepaths separate, and in relation to fixing our bloated application services, we can create separate classes for each query or command and inject them into the controller.

I also really liked Derek Comartin’s article on this.

Awww, they’re like cute little application service minis!

This aligns nicely with the standard HTTP verbs that controllers are responsible for.

Actions that handle commands typically work with HTTP POST, PATCH, DELETE, PUT (and maybe some obscure ones I can’t remember) and queries tend to be your GETs.

Here is a very basic code example of these kind of single purpose command and query classes.

First, one for the query:

public class QuoteQuery : IQuoteQuery
{
    private ILoanQuoteRepository _loanQuoteRepository;

    public QuoteQuery(ILoanQuoteRepository repository)
    {
        _loanQuoteRepository = repository;
    }

    public void Execute(int quoteId)
    {
        var quote = _loanQuoteRepository.GetByID(quoteId);

        var response = new LoanQuoteResponse();
        response.Amount = quote.Amount;
        response.RequestStatus = quote.Decision;
        response.InterestRate = quote.InterestRate;

        return response;
    }
}

One for the quote creation command:

public class CreateQuoteCommand : ICreateQuoteCommand
{
    private ILoanQuoteRepository _loanQuoteRepository;

    public CreateQuoteCommand(ILoanQuoteRepository repository)
    {
        _loanQuoteRepository = repository;
    }

    public void Execute(decimal amount, int creditScore)
    {
        var quote = new LoanQuote(amount, creditScore);

        quote.CalculateLoanTerms();

        _loanQuoteRepository.SaveQuote(quote);

        var response = new LoanQuoteResponse();
        response.Amount = quote.Amount;
        response.RequestStatus = quote.Decision;
        response.InterestRate = quote.InterestRate;

        return response;
    }
}

And one for the delete command:

public class DeleteQuoteCommand : IDeleteQuoteCommand
{
    private ILoanQuoteRepository _loanQuoteRepository;

    public DeleteQuoteCommand(ILoanQuoteRepository repository)
    {
        _loanQuoteRepository = repository;
    }

    public void Execute(int quoteId)
    {
        _loanQuoteRepository.Delete(quoteId);
    }
}

And to use them, we inject them into the controller and call the execute method upon the relevant object:

public class LoanController : Controller
{
    private IQuoteQuery _getQuote;
    private ICreateQuoteCommand _createQuote;
    private IDeleteQuoteCommand _deleteQuote;

    public LoanController(IQuoteQuery quoteQuery, ICreateQuoteCommand createQuote, IDeleteQuoteCommand deleteQuote)
    {
        _quoteQuery = quoteQuery;
        _createQuote = createQuote;
        _deleteQuote = deleteQuote;
    }

    [HttpGet, Route("api/loans/quotes/{id}")]
    public IActionResult GetQuote(int id)
    {
        var quote = _quoteQuery.Execute(id);

        return Ok(quote);
    }

    [HttpPost, Route("api/loans/quotes/")]
    public IActionResult CreateLoanQuote(LoanQuoteRequest request)
    {
        var loanQuoteResponse = _createQuote.Execute(request.Amount, request.CreditScore);

        return Ok(response);
    }

    [HttpPost, Route("api/loans/quotes/{id}")]
    public IActionResult DeleteQuote(int id)
    {
        _deleteQuote.Execute(id);

        return NoContent();
    }
}

Summary

Now we have a nice visible design evolution that shows the progressive thinning of a fat controller.

By applying the single responsibility principle to each area of bloat, we break up the complexity into smaller, easier to manage classes that can change in isolation.

We reduced the change surface to compartmentalized units that will ideally lead to a stabler codebase.

One where changes aren’t as risky and can be made with comparative ease.

If you’d like to go deep on applying the single responsibility to other controller tasks, you can hop on over to the original post, get on my personal list at the bottom and I’ll send you the Mapping DTOs recipe from the Thin Controller Recipe Set.

6 types of code you shouldn't have inside your .NET controllers

Joe Petrakovich — Sat, 16 Feb 2019 00:00:00 +0000

“Your .NET controllers should be thin”

The ever-repeated platitude with 3 metric tons of baggage to unpack.

Why should they be thin? How does that benefit you? What steps can I take to get them thin if they aren’t already? How do I keep them that way?

All valid (and common) follow-up questions. I’ve discussed part of the why in some earlier articles, so in this article we are going to take another angle.

To begin the process of identifying the steps needed to thin out controllers, we need to understand some of the common ways they can become fat.

In my experience, I’ve found 6 common types of code that sneak into our controllers that ultimately would be better suited elsewhere. This list is not comprehensive though, as I’m sure there are even more.

1. Mapping Data Transfer Objects (DTOs)

Because our controllers are on the figurative front lines of the request pipeline, there is often a need to create request and response objects if the requirements of the request are more complicated than simply using URL arguments and HTTP status code responses.

Any time you’ve got DTOs, you’ve also got a need to map the values they hold to something more functional like a domain entity.

You know, this kind of stuff:

public IActionResult CheckOutBook([FromBody]BookRequest bookRequest)
{
    var book = new Book();

    book.Title = bookRequest.Title;
    book.Rating = bookRequest.Rating.ToString();
    book.AuthorID = bookRequest.AuthorID;

    //...
}

This mapping logic is innocent enough, but it quickly bloats the controller and adds an additional responsibility. Ideally, our controller’s single responsibility is only to delegate the next action at the level of the HTTP request.

2. Validation

Obviously we can’t have bad input making its way into the inner castle walls of our domain. Validation protects us from that, usually first on the client, but then again on the server.

I like to treat controllers sort of like head chefs. They have assistants that prepare all the ingredients for them, so they can work their magic on the final plating. There are plenty of ways you can set up validators along the request pipeline in ASP.NET MVC so that the controller can assume the request is valid and delegate the next action.

This type of code is unexcusable!

public IActionResult Register([FromBody]AutomobileRegistrationRequest request)
{
    // //validating that a VIN number was provided...
    if (string.IsNullOrEmpty(request.VIN))
    {
        return BadRequest();
    }

    //...
}

Rubbish! (spoken in a Gordon Ramsay voice)

3. Business Logic

If you’ve got anything business-related in the controller, you will likely have to write it again elsewhere.

Sometimes there is overlap with validation too. If your validation logic has rules that a business person would be deciding (rather than simple things like number ranges or things a string can be), you run the risk of having to repeat that code.

4. Authorization

Authorization is similar to validation in that it is a protective barrier. Rather than bad requests making it into the domain, authorization prevents bad users from getting somewhere they are not allowed.

Also like validation, ASP.NET offers many ways to compartmentalize authorization (middleware and filters, for example.)

If you’re checking properties on your User within the controller action to grant/block something, you miiight have some refactoring to do.

5. Error Handling

It burns, it BURNS!

public IActionResult GetBookById(int id)
{
    try
    {
      //the important stuff that a head chef would do...
    }
    catch (DoesNotExistException)
    {
      //stuff an assistant should be doing...
    }
    catch (Exception e)
    {
      //please, no...
    }
}

This one is quite broad, and sometimes handling exceptions must be done in the controller, but I’ve found there is almost always a better, more localized place. And if there isn’t, you can take advantage of global exception handling middleware to catch the most common errors and return something consistent to your clients.

Going back to the head chef metaphor, I like my head chef not to have to worry about that kind of thing. Let them do their single responsibility and assume someone else will handle anything unexpected.

6. Data Storage/Retrieval

Work like getting or saving entities using a Repository often ends up in the controller to save time. If the controller’s are just CRUD endpoints, then hey, why the hell not.

I even have an older article that shows controllers with this very trait.

Rather than just calling this a bad behavior, I think pointing out an alternative way will highlight why this can bloat your controller’s unneccesarily.

First, looking at it from a design perspective (with a focus on the Single Responsibility Principle), if you have objects that are designed for persistence being used by your controllers, your controllers are then have more than one reason to change.

public IActionResult CheckOutBook(BookRequest request)
{
    var book = _bookRepository.GetBookByTitleAndAuthor(request.Title, request.Author);

    // if you've got the above statement already, you'll be
    // tempted to add the book checkout biz logic here...
    //...

    return Ok(book);
}

Beyond basic CRUD, persistence logic in the controller is a code smell for additional sprouts of logic that would be better suited deeper down the chain.

This is where I like to use either some kind of application service (behind an interface) to handle the work, or delegate to some kind of CQRS command/query object.

That’s it!

Can you think of any more types?

If you’d like to go deeper, I’ve put together a set of recipes with code samples and an exercise specifically for making your controllers thin. It is not only the how, but provides a deep exploration of the why.

You can get one of the recipes at the bottom of the original article.

Do you have weak developer boundaries?

Joe Petrakovich — Fri, 25 Jan 2019 00:00:00 +0000

Are you feeling totally and completely drained after work?

Unable to work on the projects or hobbies you used to find fun?

Is the thought of opening a text editor after the clock strikes five a laughable matter?

Well guess what?

Your boundaries probably SUCK!

Like cheap swiss cheese. And let me tell you why…

I’ve been doing a lot of self-work on personal boundaries lately.

I grew up in a home where setting boundaries were an act of treason that in my dependent eyes, would result in abandonment, or worse – death.

And because I couldn’t rely on any ounce of consistency, my strategy was instead to become utterly self-reliant. To the point where I was proud that “I’ll do it all on my own” and “never ask for help”.

Does this remind you of anyone?

When you combine permeable boundaries with a fixer-giver-hero complex, you get someone who says yes too much and invariably burns themselves out.

How does this show itself in our everyday life as developers?

Boundaries are everywhere.

Every thought you have or action you take or don’t take is a boundary line being set or broken.

An analogy I like is the maintenance of a ship whilst sailing across the ocean.

If the ship is not properly cared for, boards begin to rot, and your attention must be put on trivial distractions instead of the great path forward.

These are some of the ways we let our boundaries slip:

When we wake up and immediately grab our phones and become reactive to the onslaught of texts or social media outrage, we are sanctioning that mental state as the frame of our day.

When we leave slack notifications on while writing code, or worse – have the slack window open on one of our monitors.

When we let the loud minority of customers who complain direct our development, constantly putting out fires instead of focusing on the customers that matter most.

When we lower the bar for the quality of code we check-in. Increasing the number of times we say “I’ll clean it up later”.

When we don’t write tests when we definitely had the opportunity to.

When we accept a deadline without any push-back, despite knowing that it could result in a poor, rushed implementation.

Over-volunteering to complete tasks when you’ve already got a full plate.

I could go on for days.

This is just a tiny list, there are so many other things, micro and macro, that we do to compromise ourselves.

So – what can we do about it?

What can we do to start putting ourselves first and getting back the freedom to do more of what we love?

How can we begin to correct the course?

Just as the problem of weak boundaries shows itself as a series of tiny, day to day compromises, the solution is to apply discipline and diligence in the other direction.

First, understand that this selflessness (aka codependency) is not getting you anywhere.

People do not respect (and are suspicious of) those who say yes to everything and let their build up of stress leak out as passive aggression and resentment.

Your work starts to suffer, you stop doing things you love, you burn out and all you can do when you come home is veg out on television and cheap food (which keeps the cycle going).

Next, begin to apply tiny acts of discipline to your day that promote self-respect and really, self-love.

You’re going to stop compromising and start being kind to YOU.

Begin to identify loose ends. The areas where you accept sloppiness in yourself and others and draw a line in the sand.

Frame your day on the right foot by making your bed (a tiny win) instead of looking at your phone.

When you’re writing code, keep slack notifications off. Give your team what they need to reach you in an emergency and focus.

Focus your product’s features and support on the customers that champion what you do for them rather than the vocal minority of complainers.

Choose to slow down and not check-in code that you know could be better.

Be willing to say no to certain requests for your time when you can feel in your body that you’ve going to crash.

Implement end-of-day rituals to give your mind a real break.

Be willing to say no to features that would blur the core focus of your application.

Don’t be afraid to speak your concerns about a deadline being to soon.

Unsubscribe from newsletters that don’t empower your mission.

Unfollow “thought leaders” that bring needless drama and outrage to your feeds.

Be willing to give your teammates the opportunity to learn and handle a task without you instead of volunteering or trying to get your hands in everything.

Choose to ignore the latest hot framework and instead master your current tools.

Batten down the hatches and sturdy the ship so you and your team are empowered to focus on true, value adding work that empowers others.

So that when the day is done, you are not half brain-dead from all the fires you’ve been putting out.

As you begin to implement these changes slowly over time, you’ll notice a new energy and freedom inside you.

You’ll feel invigorated and capable.

Your team will respect your time and trust that they can count on you.

Your own physical health (and your codebase) will begin to improve.

You’ll come home, take some time for yourself, and then be inspired to work on a personal project or hobby, or spend time with a loved one without feeling exhausted.

Boundaries are everywhere.

What are you allowing in?

Ready to go deeper?

If this article resonated with you, you are probably the kind of person who recognizes the potential for greatness in yourself.

If that’s the case, I’d like to offer you an additional resource to expound upon this idea. I’ve compiled my top tools, tips, and books on building stronger boundaries.

These are resources that are dear to me that I have shared with my closest friends and family. I’ve also added summaries so you can decide whether or not it will be of value to you.

Click to jump on over to the original article location to grab it.

/end

How to stop thinking about code after work

Joe Petrakovich — Tue, 11 Dec 2018 01:50:35 +0000

I decided to do a video and written version of the same content.

The video is just me free-form speaking about it. While written is more structured.

The written can be found here.