Exploratory Refactoring

Exploratory Refactoring:

When you are working on a legacy codebase, sometimes you may want to understand the logic before you actually make changes. (Michael Feathers says legacy code as "code without unit tests". He describes lots of techniques to work with legacy code in his book Working Effectively with Legacy Code. There are bad unit tests also but that is a separate issue.

Exploratory Refactoring is an act of applying a series of refactorings to legacy codebase just to understand what the code does. During this exercise you'll check-out some of the code files but you'll not commit it. Once you understand the internal logic you'll throwaway all of the changes you made by roll-backing all the check-outs. Once you got the big picture of what changes you need to do and where to do etc. then you'll start actual refactoring and make code changes.

The kind of exploratory refactorings are like Extract Method, Decomposing Conditionals, Rename Method, Rename Variable, Introduce Explaining Variable etc. Some times its just code formatting like indentation, adjusting the number of blank lines and grouping the code fragments. During this you just want to make the parts of the code as apparent as possible.

During this phase you'll also get an idea of how clean and smelly the codebase is and how complex or easy the logic is, what is the intrinsic structure of the code, reveal the intensions of the author, which classes and functions hold what functional area of the application, and even get an glimpse of the environment like the coding and naming styles and standards followed. Overall you'll know the quality of codebase also.

You really don't have to be very careful in applying the refactorings because it is throwaway changes. The closer you get to real-life refactoring, the more you can learn from it. You will get to see some unexpected inter-dependencies, which can influence your real refactoring later on.

Keep refactoring! And develop with pleasure!

On Application Services

It can be too broad a topic to discuss application services without a specific context. So to that end I am clarifying that the context is an n-tier design utilizing object-oriented practices for supporting the modeling of a common business application.

What are application services and how do they fit into an Object-Oriented N-Tier solution?

A middle tier in many business applications is the business tier. This tier may consist of multiple layers of code including but not limited to a business objects layer, data translation objects layer, and in many cases a service objects layer.  This layer of service objects is often called Application Services because it can be thought of as the essence of the application. I like to think of the service layer's interface as the application's interface. The business objects might be the brains of the operation, but the glue that holds the application together and clearly defines what the application can do is the application services layer.  The presentation layer code can access the application services and a limited set of business objects and their interfaces in order to get work done.

An application service’s public API abstracts a business process with known inputs, outputs and steps as defined by a business analyst or user. In fact, the code in a well-defined business service should be readable by a business analyst. The result of creating a service class in front of all the object manipulation, decisions, and system state changes going on during a process is a higher level of abstraction. This pattern is essentially a façade pattern as documented in the quintessential book Design Patterns.

Why use application services?

• Separation of concerns (yes, my number one answer for everything)
• Application Services can provide a façade to complex object models or common tasks involving multiple objects.
• When requirements unrelated to the core business like security or logging is needed we can implement this code outside of the business objects yet guarantee the code is always invoked.
• Encapsulate code that changes the state of the system and may require transactions while allowing business object methods to be side-effect-free and easily testable.
• Help model a process as defined by business analysts
• Complex logic that is often viewed as a flowchart or procedural-logic-tree by business analysts can be written in a service. A business analysis could even step through the code and understand it if written well (using the same terms and phraseology of the business analysts). The brains of the operation stays in the business objects, but the service can manage the process.
• Help our object model evolve in an iterative fashion
• Object models evolve over time as requirements get more stable, changes become necessary, development paradigms shift, and we learn more about the application we are building. Sometimes, just getting the code written in a black box manner (W and X go in, Y and Z come out) can help us see our needed object model as we refactor the code.

When does a method appear in a business object, and when in a service?

My rule of thumb is that if the call changes the state of the system then it should be in the service. There are many benefits to side-effect-free functions and knowing that every business object’s method is side-effect-free it very useful (see also: CQS: command-query-segregation principle). That said, a service that does not change the system, but rather calculates a result or determines a collection of result objects might not have a clear place to live. In this case, my first vote would be to put the method in a corresponding object, an object that appears at the top of the hierarchy. OO heuristics would state that the method goes with the object that contains the most data involved in the logic. However, if this object is not very obvious then this is just another benefit of services. Instead of the client looking through the interfaces to all the related objects, hopefully they take a quick peek at the related application services.

Should application services have state?

·         State is never really needed unless the service provides sequential calls that rely on data produced in prior calls. Even then, the client could hold that data and spare the service this concern.

However, it can be very helpful for client code if the service class maintained state from call to call. This kind of a service might be called a Manager Service since besides just providing simple services, it helps manage the operation. For example a Quiz Manager might have methods for stepping back and forth through Questions and allowing the client to submit and change answers. The manager service would keep track of what question the client is on and whether or not the test is complete etc.

·         Without state the service can be used without modification for both stateless and state-full clients. For example a web front could use the service in the same way a Windows desktop application would. 

·         Without state being shared between multiple calls in a service, each individual call can be tested separately from the others.

This is a valid point, however hopefully the testing of the service is just a test of the process flow. The actual brains of the operation that will get the most testing will be the methods on the business objects that the service talks to.

·         If you give a service state it can mean that less objects need to be exposed to the client.  For example, if step 1 on a stateless service creates object X then you have to return object X to the client, even if the only purpose for X is to pass it in to service method step 2. If the service had state, object X might never be exposed and the step 2 would just check for existence before doing its thing.

          

·         A class without state could also provide its methods at static (shared in VB.NET) so a call to create an instance is unnecessary

Why should the application service layer be in the same tier as the business objects if possible?

The service layer should be in the same tier as the business object layer so we can take better advantage of object and object property scope. With a well-designed service layer façade in the same tier as the business objects many business objects do not have to be public and ones that are public can keep many of their attributes and methods internal at worst. 

With all services in the same tier as the business objects, it is easy to see what processes are affected by inevitable changes to a business object’s interface by a simple compilation of one project (which again is just a benefit of minimal scope)

The services layer should be readable by business analysts

From the dawn of object-oriented development there has been an emphasis on using coding constructs to represent real things in order to provide a clear mapping from business terms and their counterparts in code. Possibly even more important than matching up business object names with real business entities is matching up business processes and scenarios with services that match the lingo. When a business analyst explains the steps to determine the result of an algorithm or designs a flow chart with decision trees, it pays off greatly to match those exact steps, flows, and decisions in code. If the objects are named after real life entities, and the methods named after real life questions then you will find that the code in a service reads just like the documentation of the process, and it should. On many occasions I have had a business expert looking over my shoulder reading the code that steps through a process with no confusion on their part in regards to programming syntax.

We should keep in mind though that the business rules to be applied and decisions to be made are all done by business objects. The application service just knows the steps, the details are in the business objects.

Nice: If myPerson.CanVote then

Not so nice: If myPerson.Age >= 18 then

Let the application services handle the “software” stuff

What I mean by this is that we need a place to put all the code that has to do with the fact that our business is now represented in software, but has little or nothing to do with the actual business. For example, if I want to transfer money between two accounts in a banking application I would probably use two Account objects and a Dollar Amount object. However, because this is an application, when someone requests to transfer money I might have to verify security and write to an event log that tracks things people do with the system, etc. I want to make sure that this always happens when a transfer is completed. So instead of making sure the phone system, web site, and Windows application all complete these same steps I make sure that the only way to complete a transfer is to use the service I provide. The business objects know nothing about logging and security, it’s not their concern, but the service makes sure that these things are taken care of.

What’s the relationship between services and factories?

Factories are a service, granted, a specialized service that is more cohesive in regards to the objects is serves up. Factories create objects. They might be used for a simple separation of concerns so a class is not concerned with how its objects are built, or more complex reasons like data translation and abstract object creation. However it can be unclear where the logic exists for determining what object or objects a client should get on request. For example, if client code needs to get Documents related to an Account Owner’s Brokerage Account, it would be natural for the client to ask a DocumentFactory. However, what if determining the Documents an Account Owner can see is rather complex and requires information not coupled to documents like security concerns, or we want to log every time someone requests documents? In an effort to keep the Document Factory cohesive and uncoupled to security and logging concerns we might consider a service. The possible downside is that client code does not know if it should look to the Documents Service or Factory to get the object. However, if the factory does not have a public method for getting documents, a service would be the next logical place to look.

Application Services are not Object-Oriented!

I have read, heard and engaged in discussions about how application services amount to a procedural design: the antithesis of object-oriented design. I will admit to some truthfulness in that statement, but would suggest it is too broad. Rather, services that act as god classes are not object-oriented, but well-designed classes that perform a service constitute a solid design. In the seminal book Object-Oriented Design Heuristics, the object HeatFlowRegulator is an example of a Service class done right.

Where Does Business Logic Go?

Encapsulating Business Logic

How I might encapsulate some business logic? (Business logic defined here). I tend to follow a mental checklist of sorts in order to make sure I am implementing encapsulation correctly. Paraphrasing Einstein: if I understand something well enough then I should be able to explain it simply. So what follows below is my attempt to explain encapsulating business logic simply in order to see if I understand it well enough. Following the explanation is a quick example. 

Encapsulating Business Logic Checklist

1.    Clarify the logic

2.    Capture the logic

3.    Make the logic easily found

4.    Make the logic easily testable

5.    Make the logic hard to mess up

1.    Clarify the Logic

Write something down. Even in an ideal word where all requirements and business rules are written down in formal documents, we often need to restate words in the context of the system to make sure we are on the same page as the business analyst. I have done everything from typing up an official document to just having the business expert look over my shoulder at the comments of a routine. Whatever fits you and your context is great, just do it.

2.    Capture the Logic

Regardless of where I put the logic at the end of the day, first I just want to start capturing it in code, thinking about it from a code point of view.  This is the first stab at design separated from all other concerns as I start writing code to implement the logic. The classes involved are determined as I go through typical black-box thinking: Given A, B, and C how do I determine D?  This naturally leads to the next step of making this logic easily found.

3.    Make the Logic Easily Found

I need to make this logic easily found for the next guy who is going to update this logic or gasp, fix my bugs. As an object-oriented developer, I know the business logic belongs in an object, but which one? The short answer is the obvious one. Often a particular object seems to be the most natural choice and we don’t give it much thought. However, when multiple objects are involved the general rule is to pick the object that has the most data involved. If multiple objects appear equally involved THEN JUST PICK ONE, you’re thinking about it too much now.

4.    Make the Logic Easily Testable

Business logic is arguably the most important code you will write. It determines how much should be paid or charged, calculates values, determines answers, figures whether a missile should zig or zag, etc, etc, etc. If you are going to bother writing any tests, test your business logic. Furthermore, make the tests so fast and easy to run that no one has a problem with running the tests all the time. If you find you can’t easily and repeatedly test your business logic because it requires database connectivity, complex object creation, or whatever, then think about changing the design.  It’s also true that making your logic easily testable with solid tests can go a long way towards clarifying the logic and design. This is one of the touted benefits of test-driven development.

5.    Make the Logic Hard to Mess Up

Those who make the leap to programming objects as opposed to just programming with objects will see a huge improvement in quality simply because things become harder to mess up. There are many things we can do, but two common approaches include making objects for any business concept and making objects immutable. For example, if a password has to be more than 3 characters but less than 10 and include letters and numbers then create a Password object that encapsulates these business rules and has methods for accessing them. It should be impossible for invalid passwords to be bouncing around the business layer of an application. If an Email requires an IP address of an SMTP server to send itself, then do not make a property called IP address that may or may not be set at the whim of the caller, or get changed somehow during a process. Make the IP address required upon construction and unchangeable. The users of that Email object are much less likely to mess things up.

Simple Example

For the sake of discussion, a simple case (A simple cases because we can focus more on the process and less on the complexities of the example). If you use your imagination you could apply the checklist to more complex scenarios as well.

I have a class I’m creating called Message Header, and I need to increment a value (Message Number) each time I create an instance of the class based on a previous message number.

Clarify the logic

After a few emails we established the following details about the business logic

• At this point we don’t know where the last message number comes from
• Message Number is an attribute of Message Header
• The new number should always be the next even number (2 more than the previous)
• The new number should always be between 2 and 9998 (inclusive)
• After 9998 the message number should reset to 2

Capture the logic

I create a function called DetermineNextMessageNumber that takes in the previous message number. Code is written to encapsulate the logic above. Defensive code is added to throw an exception with the simple exception handling if expected assumptions are not met – like assuming the previous message number is always even.

Make the logic easily found

The obvious choice was the MessageHeader class, so I add the method as an internal/friend static/shared method to the MessageHeader class.

Make the logic easily testable

I create 5 quick tests to test the logic: a normal case - passing in the number 6, two edge cases – passing in zero and 9998, and two possible extremes – passing in -50 and 55223. This prompts me to ask the business analyst what to do in these extreme cases. She claims both are exceedingly unlikely. So I figure my defensive coding with the simple exception handling will be perfect for when the cases do happen. My tests require no database access and no complicated object building. No changes seem to be needed, the method is easily testable.

Make the logic hard to mess up

I don’t create objects with settable attributes by default so I know the user could not easily forget to set the Message Number. However, I realize that someone could create a Message Header and not realize there is business logic that determines the correct next number. To fix this I change the constructor on the Message Header class to take in the PreviousMessageNumber. The constructor will then call the DetermineNextMessageNumber making sure that a coder cannot generate a Message Header without applying the appropriate logic. Since the constructor handles the logic I realize I can reduce scope issues by making my DetermineNextMessageNumber routine private. For half a second I think that maybe I should make a MessageNumber object that will guarantee a valid integer between 2 and 9998 and thus separate concerns more, etc. However, the expert said it is rare, and I am throwing a simple exception in case it does happen, I think the design is good enough for now.

Summary

Get your logic right, get it in code in the correct place with good tests, and design so that the next guy will have a hard time messing it up.

When I see the code of developers trying to do more than just object-based code the most common blunder seems to be leaving business logic all over the place. The most common misplacement seems to be in user interfaces, however, well-meaning developers often move the logic out of user interfaces but then misplace the logic in factory code, service classes, stored procedures, etc. 

When object-thinking is applied I think logic starts to naturally fall into place without much thinking or time-consuming analysis. 

What is Business Logic?

Business: Commercial enterprise: the activity of providing goods and or services involving financial, commercial and or industrial aspects

Logic: The principles that guide reasoning within a given field or situation

Business logic code is the code that applies the principles that guide reasoning within the business. Sounds fancy, but in fact it is just the code that makes decisions, answers questions, and applies rules. One might argue that in the common business application the business logic code is the most important code. The code you cannot write unless you understand the business and as such is often defined by experts in the field.

What is not business logic code?

In short: all the other code.  Often the common business application also requires code to handle user interaction via graphical user interface components.  There is often code for database access, code for capturing process algorithms, code for handling security, code for logging interaction or auditing events, code for managing errors, code for wrapping external services or components, etc.  These subsystems are all required to complete the application, but are often not directly tied to the business itself.  As mentioned above, business logic is defined by a subject matter expert from the business the application is being built for, however the developer or other related technical authority is often the subject matter expert for this other code.

This is so clear, could you please add some confusion?

Yes. The subsystems noted above (data access, user interface code, etc.) also have principles that guide the reasoning related to them. So although these subsystems are not tied directly to the business at hand, they do have their own business to attend to and so the logic involved is also technically business logic. This is important for the object-oriented developer since the objects created to handle these subsystems should also be responsible for their own related business which of course is not the business of the application. This is worth noting because often object-oriented developers drop their respected OO principles when working in these other subsystems outside of what they would consider business logic. I did just that until it dawned on me that I was missing all the benefits of an OO design outside of business code.

Why is it important to identify business logic?

• Business changes frequently and we have to know where to look, what to change, and how to easily test our changes
• When discussing the logic with subject matter experts after it has been implemented, we need that logic isolated and at the right level of abstraction without peripheral distractions to minimize logic-to-code translation
• So the business logic code can be kept separate from other code to make sure changing either has little to no effect on the other. Rude developers have a habit of spreading business logic all over an application from the user interface through stored procedures
• We have to be sure not to duplicate business logic so when it needs to change (as it is highly prone to do) we make sure the logic is changed and fixed for all code dependent on that logic
• Business logic is often tied back to requirements to make sure features are implemented correctly

What I might point out is that it might still be wise of us to track the difference between these two types of business logic. For what is often the case is that one tends to be an add-on to the other.

Imagine a system that manages insurance details for customers. The business logic relating to the business of insurance may exists along with business logic that deals with the business of security along with some auditing requirements. Understanding these separate needs, these separate businesses is necessary in order to keep concerns separated and allow for objects that have just one reason to change (SRP: Single Responsibility Principle) of SOLID design principles . In an ideal design the object that has business logic related to insurance would not also contain logic that has to do with security and or auditing. We should be able to make changes to our security model (or swap it out entirely) without breaking our business code.

The 4 Aspects of Every Application: Part - II

The first part has to be read and understood so this post can be understood in that context. 

The business-object-oriented applications have at a minimum 4 aspects: Business, Process, Maintenance, and Infrastructure.  These are not full-blown design patterns of the GOF variety, but rather patterns of design for a single object.

The impetus here is that for a singular concept, there are four aspects of our applications that have to deal with it (This is only untrue when our application’s total emphasis in on just one of the aspects. I think that is rare, but either way these objects are in the context of the common business application where all 4 are usually in full swing). As a firm believer in a separation of concerns, encapsulation, and cohesive objects that do one thing well, I often end up with different objects for each aspect as opposed to one object that does everything. This leads me to answer the question then: What do I want from a class in order to fulfill a particular aspect.

In each case below I refer to a business or domain abstraction. I don’t want to use the term “object” or “class” since the whole point here is that many classes might represent the same abstraction. So to be clear, in a blending application a Blender is a business abstraction that might be represented in code by multiple classes.

The Business Aspect

In this case I will want an immutable class so that it is automatically thread-safe and has no synchronization issues. This immutability will also ensure that this business object will not have to worry about the effects of changing state, worry about being invalid at any time, or be concerned about being changed by outside operations. Aside from immutability I would expect that this class’ design would ensure that every method of the class is directly related to the business of that class…in other words, cohesive in respect to its business. More so than other classes, encapsulation is of the utmost importance as we want to know where all business logic related to the data of this class is located. Exposing any property (data) would be strongly questioned. This class would provide an interface to work with relationships that have to do with the business. Any changes to business rules and logic affect only this class.

The Process Aspect

In this case I need a class that encapsulates a process that is directly related to an abstraction in the domain. Its code base would be very thin as it would only layout the flow of the process but not be concerned with how anything gets done. Its methods would have to do with the process alone. This class might have to have feedback mechanisms or methods that help outline steps in the case of user input that is required along the way. This class’ design would ensure that every method of the class is directly related to the process the class handles…in other words, cohesive in respect to the process. Any changes to process flow affect only this class.

The Maintenance Aspect

In this case I need a class or classes than can help me with the general maintenance of a business abstraction. More often than not this is simple CRUD stuff for the abstraction’s data. This class might be mutable if a partially built object makes sense. The methods of this class would all be directly related to the maintenance of this business abstraction, in other words, cohesive in respect to maintenance. This class would provide an interface to work with relationships that have to do with maintenance only. This class’ design would also be less encapsulated because its purpose is often to work tightly with the data behind a class.  Any changes to validation or other maintenance rules affect only this class.

The Infrastructure Aspect

In this case I will want classes that handle the fact that a given domain abstraction is being represented in a software application. There will need to be infrastructure in place so a domain abstraction can, for example, be persisted in and reconstructed from a database. Because of the nature of infrastructure these classes may not have any state, but rather just act as a library of functions. Any changes to infrastructure affect only these classes.

Object Relationships of Modeling

Understanding the object relationships goes a long way towards a solid object model design. I've gathered few notes on this subject and produced the following brief summary for reference purposes.

Is a kind of – A Car is a kind of Vehicle, An Orange is a kind of Fruit

• Implies inheritance
• Typically this relationship is called is-a, however that is just not as clear. Using is-a often results in a poor model with things like a Boss is-a Employee which leads to roles being implemented via inheritance, etc.

Is Part Of / Is Made Up Of /Composition – A page is part of a book

• A book is made up of / composed of a Cover and Pages
• Implies that the part does not exist outside of the whole. If you destroy a book, you destroy the cover and pages.
• Part-of relationships suggest that internal objects may be best left hidden and accessed via methods on the parent
• Book.TurnPage() instead of Book.Pages.TurnPage()

Containment / Aggregation – Point of Interests and Paths are contained in a Map

• One object acts as a container, grouping other objects together for a purpose. The parts are not dependent on the whole. If we destroy a Map, the Points of Interest are not destroyed.

Associated With – An author is associated with a book and vice versa

• Associated With relationships suggest that the related object is not owned by the parent like the part of relationship, and is often accessible via navigation through the domain model
• Book.GetAuthors()
• RaceCar.GetDriver()

Helps Describe / Identifies – A Title helps describe a Book

• Implies that the object is inherent to the parent object and there is often less danger in exposing the object outside of the parent

Feature of / Implementation - Features of a Book include its Width and Height

• Unlike an object that helps describe or identify another object, a feature of an object is one that should rarely if ever be exposed
• Business logic is naturally written around features of objects. In fact, if an implementation-related object is not referenced in the business logic of the parent object we should consider removing the object

Uses – A Book uses the Pages to get the number of times a word appears in the book

• Clarifies collaboration among objects
• The uses relationships is often another relationship aside from how two objects might be related (Part of, Associated with, etc).

Note 1 – One might expect to find the relationship has-a in the list, but it is too vague to be helpful. Part Of, Associated With and Helps Describe are all often referred to under the fuzzy has-a umbrella.

Note 2 – These are logical relationships. Based on external factors, for example, we might decide to physically contain an object that is logically an association.

Note 3 – You may well find as I have that the terms Containment, Aggregation, and Composition are often used interchangeably. However, I think it is important to understand the types of relationships regardless of what they are called.

The 4 Aspects of Every Application: Part - I

Application Point of View

I think nearly every software application project can be thought of as having the following 4 aspects: Business, Process, Maintenance, and Infrastructure. How you design your application has a lot to do with your point of view and which aspect you think should get the most emphasis. A common mistake is to view every application from the same point of view and thus one aspect gets the most emphasis every time. The aspect you give the most emphasis to will obviously affect every facet of your design including your object designs.

Business: This is code concerned with applying business rules and logic to determine what needs to happen in a given situation.

The result is a business-oriented application, one where the most effort is in making sure the business is correctly modeled and understood. This emphasis is valid for the common business application where a developer is trying to mimic a business as described by a business expert. A telltale sign of a design effort that is focusing on the business is that the main artifacts of design are business object models. Often the first thing designed is a rough sketch of the business entities represented as classes.

Process: This is code that implements a process which when completed accomplishes a required goal.

The result is often, as the name implies, procedural code. Or at best, the result is an object-based design where objects are used to hold data, but all the "thinking" code is in the process routines, not the objects.

Maintenance: This is code for the direct creation, changing and deleting of things in the application.

The result is generally a data-centric application where the business is viewed as just adding, removing and changing data in a system. A telltale sign of a maintenance application is when the design effort begins with designing database tables. From the very beginning the emphasis is off the business and geared towards the data instead. This kind of emphasis is valid for applications where truly the creating and changing of data is the primary focus. For example, something like a contact management application or some sort of activity logging application lends itself to a maintenance-focused application.

Infrastructure: This is code that is a result of the simple fact that we are writing software. Examples include code that maps objects to data and vice versa, security and logging for auditing purposes.

The result is often an application that does not model a business but rather reflects the implementation of the requirements. Often the goal of the developers in this case is to achieve something technically difficult. This kind of focus is valid for something like grid computing tools, framework libraries, etc. The business of the application is often technical in nature.

So what’s the point exactly?

A common mistake is to approach every application with the same emphasis in mind. I have found the most common mistake when designing the common business application is to design the application like it is a database-babysitting application.  In other words, the whole application is approached as if the business is all about Maintenance. The actual business logic is lost in the shuffle between inserts and updates. Furthermore, I think because business applications lose their business focus, developers who are intrigued with an object-oriented solution can't figure out exactly how to apply those OO principles to the multifaceted world of the common business application.