J. Kerney Opinions and Notes

Where is the pride?

2008-06-30T17:10:00.000-07:00

Where is the pride?

Lately I have been doing a lot of talking in user groups and technical engineering forums. This has put me into a position to talk to several professionals within the programming community and I feel I have learned quite a bit about “Programmer’s Pride.” This has left me with the feeling that we as a professional group pride ourselves in the wrong thing.

Being that our profession is a “Thought works” profession means that we are proud of our thoughts. Thoughts are hard to measure though and so we use a different metric to determine our ability. We measure how good we are based on 2 metrics: how difficult of a problem we can solve and how fast we can solve any problem.

The problem with these metrics is that they are not temporal. Once the task is completed there is nothing to show that illustrates the difficulty of the problem or how fast we achieved the solution. As such these metrics have no lasting meaning or value, and in the end are empty.

It has become my belief that the reason programmers get offended when you critique their code is that they know it is not the best it can be. They know this but still derive pride from the fact that it was a difficult and they solved it in a day.

This is not the way it should be. The professionals in our field should be able to feel pride in all of our workmanship, not just the fact that we did it fast. So we need a new metric to measure our ability by. One with a temporal element that shines long after the deed has been completed.

I suggest using the metric of maintainability as a measurement of pride. We need to take pride in how maintainable our code is because this determines how long our code will live. It also gives us the ability to have a physical representation of our pride that can stand on its own. We will no longer have the need to defend our code as it will be self credible.

The nature of design patterns

2008-06-20T16:44:00.000-07:00

Eating fresh chocolate chip cookies got me thinking about design patterns and how we use them today. Most places and people think of design patterns as cookie cutter solutions. If a developer knows design patterns he can write code faster because someone else has already solved the problem. They also see design patterns as a way to cut a problem into nice architectural shapes. I have come to believe this view of design patterns is wrong.

Alan Shalloway, in his talk, said “Design patterns do not lead to good design. Good design leads to design patterns.” That one sound bite has resonated with me for almost 2 months now. I have rolled it around in the empty space of my head where a brain is rumored to exist. It has forced me to re-look-up design patterns and restudy the few I know and somewhat cling to. I have dug out my anti-patterns book and hit websites.

I have determined that I need to read Refactoring to Patterns by Joshua Kerievsky. But more than that I realize that the way in which most people (based off of internet comments) use design patterns is failing. The idea of taking a problem and applying to it a design pattern that seems to target that domain is flawed except for the few who are truly gifted in their understanding of patterns.

So if the world seems to be going wrong then logically one of two things that can be wrong. Either the tool is bad and unusable, or it is being used incorrectly. Design patterns make since logically. We can see how given a specific problem we CAN solve that problem as described by the pattern. However there are good criticisms against doing that. At the bottom of this page there are a number of good points about the flaws of patterns.

So I say that the tool is not bad, just being used incorrectly. A large number of patterns came into existence by finding them in successful projects. We did not discover them by trying to find a generic solution to the an existing problem. So they were there before anyone knew about them, and they led to success. I am not saying that we should not learn about the design patterns already discovered. I believe the absolute opposite of what we need to do. I think every developer should become intimately familiar with at least the "Gang of Four" patterns plus a few others for scope.

But once we have this tool what do we use it for? I think design patterns are a ruler intended to help us measure a design rather then a cookie cutter that shapes our project. If design patterns are recognized when our code is forcing us to go in that direction we can better refactor to gain the most of the solution that presented itself as the natural solution.

We should let the solution drive the design not the other way. Once we take this approach we find that all the criticisms for design patterns no longer apply. We discover the pattern that was already there and simply removed the excess stone. It allows us, the programmer, to truly focus on the art and not on the rote. It also guarantees that the solution is what was needed not what we thought was needed.

The last thought on this is a simple one. This is not easy to do. I know when I start to hear a problem I automatically start trying to stamp it with a pattern, hoping that I can place the patterns so that there is no problem not covered. But anyone who has ever baked Christmas cookies knows that no matter how carful you are, there is always leftover dough. All I know is I am trying, and getting better.

Good Agile – Good Agile

2008-05-08T17:39:00.000-07:00

I recently read this blog post Good-agile-Bad-Agile and would like to address some of the issues I have with it.

The larger picture issue is that the poster does not seem to understand what Agile is. He makes the assumption that Agile is XP or SCRUM. XP and SCRUM are methodologies that are intended to help a company achieve Agility and are a flavor of Agile. Agile is not XP or SCRUM. This is an important distinction, because any methodology breaks down once you follow the letter not the intent.

Agile is 4 values. Any thing that violates any of the 4 values is not Agile. Any thing that upholds the 4 values can call itself Agile, but Agile is not necessarily that thing. Those 4 values are as follows:

Individuals and interactions over process and tools
Working software over comprehensive documentation
Customer collaboration over contract negotiation
Responding to change over following a plan

I got these from the Manifesto for Agile Software Development published in the cover of: “Agile Software Development Principles, Patterns, and Practices” written by Robert C. Martin.

The poster claims that all Agile with a capital ‘A’ is bad and a religion for the stupid. I have general problem with this because it discredits a lot of people’s intelligence. Whenever you hear someone overgeneralize about the capabilities of a large group you need to take care and call into question anything they say. They need to provide good solid arguments to back such claims up.

Agile was discovered the same way as design patterns. A group of people noticed that there were successful software development amongst a forest of failures and wanted to know what was different. You cannot scientifically quantify how much design patters have helped any project but you can show that successful projects use design patterns. The same is true of Agile.

All successful projects use Agile even if they are unaware of it or do not name it as such. The poster describes what Google does as “Good agile” but tries to argue that it is agile with a lower case ‘a’. That is, the methods they use are agile like a cat, an adjective rather than a noun. But the environment he describes is Agile, as it follows the 4 values of Agile. It may not be XP or SCRUM, but it is Agile.

So now to the nit picking. These are point-by-point answers to his issues.

1. He claims that 90% of people execute Agile incorrectly. I am not going to bother arguing numbers, that is pointless. But let's assume he is correct. The vast majority of people develop software in other, less effective ways. From where I am sitting 10% executing development correctly is one hell of an improvement.

That aside, let's take look at why so many people execute Agile incorrectly. Agile is a significant change to the way people are use to doing business. So they fear the change to the extent they do not actually change their practice. They only use the pieces of different Agile methodologies that easily fit into their current way of doing business. And in the end they do not do Agile at all, they simply call it Agile.

The last problem I have with this statement is the poster says there is a problem but gives no solution. I will bet most other companies that tried to run their business like Google will find they do not have the money to do so. I would love to work for Google but Google’s process will not help my current company.

2. The poster talks about Agile being too focused on time. I would like to point out that time is not one of the four values of Agile. That being said most companies need to know when something will be done. The methodologies for time estimation in XP and SCRUM are not intended to force the programmer to comply to a schedule plucked from thin air. In fact, both XP and SCRUM actually expect that no schedule will be met. Instead they use the time matrices as a way to communicate the current status of the product to the customer. They are not intended to get in the way of normal operation and therefore should not stop people from helping their peers. You are not driven by the schedule estimate you are only using them to better communicate unknown complexity and problems to the customer.

3. Cowboy programming is bad. I can even tell you why. Cowboy programming is done by those who are exceptional programmers who feel that they are better then anyone else and therefore do not conform to coding and testing standards. I have known truly brilliant programmers that the idea of working on their code causes me to shudder. This is bad and in my opinion makes them no longer a brilliant programmer because a good program is maintainable. When one cowboy meets another at the OK corral, you better believe there will be a showdown.

In short everything the poster complained about was where old process disguised itself as Agile, and everything that he mentioned that was good followed the Agile tennets. While it can be easy to simply criticize something to dismiss it than it is to form well-thought-out arguments, this blog tended to focus on superficial, personal issues rather than a formal debate on the merits of Agile.

The Principles of Object-Oriented Design part 4

2008-04-16T13:04:00.000-07:00

The Interface Segregation Principle

The idea behind the Interface Segregation Principle is that no object or process should know more about the object it is using then it absolutely needs to do its job. Lets say that object ‘Widget’ is used by 2 separate process that both use a widget in slightly different ways.

So what we want to do is take the public properties and methods and have the ability to “chunk” them into 2 manageable bite size pieces. We do not want process 1 or 2 to have reliance on public portions of a widget that they do not use.

This then means we have to develop a class hierarchy that allows all common features of widget to be seen by both processes such that they do not see or care about those features that are not common.

The Principles of Object-Oriented Design part 4

2008-04-11T18:45:00.000-07:00

The Dependency Inversion Principle

The only way I can think to describe this is to talk about a project I was on in my recent past. We had a large N-Tier application with several different functional areas. A lot of these functional areas relied on functions performed by other areas in order to manage complex business scenarios.

So for any given use case you would have one entry point and that entry point would then make sub-calls to other part of the system to complete its given task. Quickly we realized the danger in this relationship and abstracted interfaces owned by various parts of the system we were calling to.

So now we have business scenario “Create Widget”. Create Widget is part of the widget functional area and specifically belongs to Widget Factory. Widget Factory needs to call “Check Warehouse Quantity” for Widget Parts. Check Warehouse is part of the Warehousing functional area, and specifically part of the Warehouse object. Check Warehouse Quantity calls the “Create Custom Message” method to request information from the warehouse location. Create Custom Message is part of the Communicators functional area, specifically the Communication Stream object.

So now I add a new type of communication stream that uses an http request. When I compile the Communicators functional area it also forces a compilation of the Widget functional area even though widget knows nothing about the communicators. Now that may not seem too bad.

So now several classes have been added to the Communicators functional area. We realize that we are violating the Open Close principle. So we refactor to make the code more maintainable. We build and suddenly the changes we made cause Widget to need to be changed. This shows us that our code is frail. The problem is there is nothing we can do about it…

Or is there?

The dependency inversion principle is about preventing/fixing this. So this is how the principle would be applied to the above scenario. The Communication Stream would inherit from an interface provided in the Warehousing functional area. The Warehouse object would inherit from an interface provided in the Widget functional area. Now when we refactor the Communicators functional area we change all the classes and maybe create an adapter to implement the interface provided by the Warehousing functional area. We compile the communicators and the widget lives as happily as it ever has never knowing about the drastic changes made to the communicators.

It is important that the using functional area owns the interface as it accomplishes two things. The fist is it forces changes to that interface be made while changing the functional area that uses it. This at least raises awareness by the developer who is making changes to implementing functional area. The second thing it does is it prevents one build from causing another area to build needlessly.

There is one more thing I would like to say about this. Alan Shalloway has a great quote that I think is very important here:

“An object may either create or use another object but never do both.”

The Principles of Object-Oriented Design part 3

2008-04-08T17:50:00.000-07:00

The Liskov Substitution Principle

What is wanted here is something like the following substitution property: If for each object o(1) of type S there is an object o(2) of type T such that for all programs P defined in terms of T, the behavior of P is unchanged when o(1) is substituted for o(2) then S is a subtype of T.

Barbra Liskov, 1988 re-quoted from “Agile Software Development Principles, Patterns, and Practices”

That is a very precise and confusing explanation of what is desired. Let’s break it down. We have a program that uses type T objects. If we give our program an object of type S and our program still works as it did before then we can say that S derives from T.

That makes it a little easer to understand but does not explain what it means because there is a lot of subtlety to its meaning. The first question that comes to mind is: Isn’t it the point of extension to change the behavior of the program? Or: If my subclass doesn’t do anything new why would I create it?

Ok, so this is what I have gotten out of this. A subclass’ intent is to extend a program not change it. So if a program expects a call to a method to perform in a certain way it should, though it can do more. But even that is incorrect…

Let’s look at this from the reverse. Rather than trying to explain what Liskov’s Substitution Principle is, let’s try describing what it isn’t and work our way back.

The problem occurs when a program using the parent type and unaware of the child type makes a call on an object the child either does not support or does not support well. This then caused either an error to be raised or unexpected behavior of the program.

This is the situation that Liskov was trying give us guidance to avoid. But again we are hit with subtleties. If a base object overwrites a property such that it makes it the same as another property that is a violation of this principle. If the base object expects a parameter to be passed of a certain type and the base object has no such restriction, this to is a violation. Also, if the program makes a call against a method on the base object that does nothing is a violation.

In short this principle is about strict adherence to the contract set forth by the objects we inherit from. If we find that we violate those contracts we violate this principle and we should consider redesign.

The Principles of Object-Oriented Design part 2

2008-04-08T14:02:00.000-07:00

The Open Closed Principle:

Robert Martin Defines the Open Closed principle by saying that an object must be open to extension but closed to modification. This is one of the most commonly touted principles in software. It is sometimes called the single use principle.

The single use principle is: all objects and methods must have a single use.

Another way to state the Open Closed Principle is to say that an object has only one cause for change.

All these sound easy, but they are often violated, and in fact violated in the name of following them.

This is caused by misunderstanding of the meaning and intent of this principle. A phone object is intended to call another user of phone. This includes, checking for dial tone, allowing the user to dial, ringing when a call comes in, and passing the verbal message from one phone to another.

So this is the single responsibility of allowing a person to make a call… Or is it? In fact there are five responsibilities. If you count the responsibilities listed you will only count 4, but there is one implied responsibility. That is the responsibility in orchestrating the other 4 responsibilities.

So back to the actual principle. There are two parts of this principle and both are have very deep meaning in Software development. The First part is Open to extension. It is the hardest for me to wrap my brain around and try to describe. This has to do with inheritance, and more importantly inheritance done correctly.

Ideally, you should be able to extend the system, by simply inheriting from base classes or interfaces, with no modification to any code that uses those classes and/or interfaces. This is a two way extension. You not only extend the capabilities of the base class through inheritance but you also extend the functionality of the program. You accomplish both things by one act, and to the same end. The system can now do something it never did before.

The second half of the equation is: closed for modification. To be closed for modification means that to get the system to perform more, you need not modify existing code. Now no code is ever completely closed for modification, as we will never write perfect code. So Robert Martin advises that you remove causes for modification when you find them. So if there is a change to a system that requires you to change code to extend behavior, refactor.

The Principles of Object-Oriented Design part 1

2008-03-10T22:26:00.000-07:00

So I have been reading Agile Software Development Principles, Patterns, and Practices by Robert C. Martin. As such this is what I intend to make the next few posts about.

So the principles of software development as defined by Robert Martin can be broken up into 2 categories. There are those for development of applications and those for packaging applications.

The 4 principles of development are:

The Single Responsibility Principle
The Liskov Substitution Principle
The Dependency Inversion Principle
The Interface Segregation Principle

The 6 principles of packaging are:

The Release-Reuse Equivalency Principle
The Common Closure Principle
The Common Reuse Principle
The Acyclic Dependencies Principle
The Stable Dependency Principle
The Stable Abstraction Principle

My goal at this moment, provided my reading does not get high-jacked is to post on each of these principles and what I think they mean.

These principles are very important in Software Engineering. Though, what I find most interesting about what this book has to say is that it warns the reader about over use of any of these principles. They should only be used where need has been discovered and not before.

Technical Debt

2008-03-06T09:02:00.000-08:00

I have spent a lot of time discussing and thinking about technical debt over the last week. And so I decided to consolidate my ideas and write them down so I can reference them later.

In this discussion I am going to assume only salaried employees, but the same works for wage employees, it just adds unnecessary complication in the description.

To understand debt, we have to understand the bank, and how the bank is used. Generally we know that we put money into a bank and we collect interest on that money. With technical debt we deposit money, or time into the bank and collect interest in money out.

So from the view point of the employee, the employee deposits eight hours into the bank every day when he arrives at work. For those eight hours the employee gains one day’s pay. The interest rate of those hours is equal to the total pay gained divided by the hours worked, or in short the hourly rate the employee gets paid for the day. Every hour the employee works for a single day’s pay decreases their interest rate.

At the beginning of the day the company pays money into the bank and gains profitable work from each employee. The interest rate for company is equal to the number of hours an employee works divided by the amount of profit earned for that employee’s work. The less profitable the work the employee does, the lower the interest rate the company gains on their investment.

What is profitable work? Profitable work is work that directly provides product or service that is sellable for more then it costs the company to produce, or work that reduces the cost of producing that product or service.

Ok so if there is profitable work what is non-profitable work? Non-profitable work is work that has no value to the customer. This is training of employees, examining code so that we can understand it, and a host of other things a company must do just to run their business.

Now for my definition of what technical debt is. Technical debt is time and money that must be spent performing non-profitable work before profitable work can be done. In programming we see this most often when a programmer needs to examine a piece if code to understand it before they can safely modify it. The modification has direct use to the customer and therefore can be sold, the examination cannot be sold.

So by this definition there is no such thing as debt free code base. Every piece of code requires someone to pay in a small bit of time before they can change functionality. But we can calculate the impact of debt, and measure if it is acceptable debt. Acceptable debt is debt that has little or no cost to the company’s and the employee’s interest rate.

Now the above definition is missing one thing. It does not quite follow our understanding of debt. After all we have a bank, but it does not appear that we borrow from the bank. Well here is my understanding of how it works. In the bank we deposit time and/or money and expect interest. But occasionally the employee does not have enough time, or the company does not have enough money in the bank to cover producing their product or service at the highest quality. So we cheat. We allow the product to go unattended, with lower quality, knowing sometime in the future we will have to fix the lack of quality. So we borrow time from the bank, because we are promising the bank that we will spend so much non-profitable time in order to reduce the impact of the decision we made now.

Now debt acquires interest, just like real debt. This interest is caused by time. As debt is left unattended it becomes harder to remember what caused the debt and therefore fix it. It also makes it harder for another change to be entered into the code base without acquiring more debt. At which point you get compound interest.

The measurement of technical debt is the number of hours it will take for an equally capable person who is unfamiliar with the specific area to examine it and safely make a change to the way that area performs divided by the hourly rate of that person. If the number is large, you have a low technical debt. Lower the number becomes the more technical debt that has accrued. If the number ever drops below 1, then that section of code is technically un-maintainable. That does not mean a project will not be scrapped well before it ever approaches 1.

Business Ethics

2008-02-22T18:58:00.000-08:00

Introduction:

I got into a conversation about business ethics with a friend of mine, and I thought I would put down the musings of that conversation and how business ethics effect and are effected by Agile. (As I see it mind you, I am still learning.)

First I would like to say I have a problem with the term “Business Ethics.” My problem is with the “Business” in the term “Business Ethics.” This makes it sound as if these are a sub-portion of ethics, and somehow lesser in weight and meaning.

So back to business ethics.

I would like to start with an Explanation:

I see that ethics are divided into two separate forces, Duty and Honor, and the interaction of those forces. Here is the way I define these terms: Duty is the responsibility to complete an abstract task, while Honor is the responsibility to handle things fairly and truthfully.

The key word in the definition of Duty that I provide, is abstract. When speaking of Duty as a moral force, it has little to do with defined tasks. Doing a task that is asked of you is not Duty. Duty has to do with why you do it. It is upholding a larger abstract task. If you perform the task because you wish to make things easier for the person who asks you to perform the task you are starting to show Duty. As this is a step in the accomplishment of the greater abstract task it is driven by Duty.

Duty is not transitory, as it is the willingness to complete an abstract task. Completing the task is almost as important as the fact that the task is abstract. If your task is to make some one’s job easier, then completing one defined job for them is not the completion of the overall abstract task. It will require more effort and therefore more Duty to perform.

Honor is the responsibility to handle things fairly and truthfully. The statement about fairly and truthfully make this definition in contradiction with itself. There are times when in order to be fair, you cannot be 100% truthful, and other times when to be truthful we cannot be fair. So honor becomes further divided between two other forces.

To handle things fairly, requires you to look at things subjectively and analyze what is most equitable to all parties involved. This does not mean that all parties involved should be considered as equal. When looking at a situation, one must consider the involvement/commitment of all parties. To handle some one who is barely invested in the situation may not be fair to those who have heavily invested into it.

To handle things truthfully is simpler. You must first be honest with yourself, and realize your own bias in a situation. You have to be willing to report things as they appear to be, and that it is how they appear, not necessarily as they are.

Agile and Ethics:

Ok so we now have a few definitions. What does this all mean?

As a software developer I have in the past found myself in situations where expectations did not match promises. I have worked in environments where the customer was considered hostile, and when the product was finished the customer paid for it and never used it.

The way I would like to look at the organization of a software project is different then a manager or even a company looks at it. I would like to look at in terms of Duty and Honor.

Every practice that Agile employs appears to increases these two factors across the whole company. I am going to take practices from “Agile Software Development Principles, Patterns, and Practices” by Robert C. Martin and explain how they increase business ethics.

Again I would like to say this is for my own education, so I may make mistakes. If I do, please inform me.

Individuals and interactions over process

When there is a process in place, that hampers what someone does, how can they be both fair and honest? I have seen this time and time again. “It was OK’ed not my problem.”

Honesty and fairness means being willing to do what is right regardless of process. Honor, is about handling a situation as it needs to be handled, not as it is deemed to be handled.

Working software over comprehensive documentation

Once you have worked in this field long enough you learn that documentation is a lie. To make things worse is: It is an expensive lie. A point that Llewellyn Falco made was when you pay someone as much as you pay them in our field, why would you want them to spend hundreds of hours maintaining documentation when they could be programming. So this becomes an issue of Honor.

But it gets worse. We often have to decide: get more code done, or document. In most cases the choice is get more code done. When someone else whishes to use code that is dependant on documentation to be understandable the documentation is wrong. So now we have a Duty to our company to provide code that is maintainable, and we now have failed in that task.

Customer collaboration over contract negation

How can the customer, the company or the programmer communicate to fulfill their Duties? We know in the industry that no one really knows what software is supposed to do. When a product is delivered, the customer finds that it does not help.

By constantly working with the customer, letting them try the product in small increments, they can guide the product into being a more complete and useable product. This increases both Duty and Honor.

Duty because everyone involved can see the abstract task form, and process toward completion. Honor, because it removes fear of a law suit, and increases open communication between all parties.

Responding to change rather then following a plan

This is really a sub set of the first practice, “Individuals and interactions over process.” A plan is process. Allow the individuals to do what they can to handle whatever situation comes to them, and they will handle it fairly and honestly.

Conclusion

Agile appears to be one of the most Ethic ways to produce software I have ever been introduced to. It makes sense once you get over the fear of the apparent radical shift in methodology. I am completely enjoying my education.

A better way

2008-02-10T12:46:00.000-08:00

I often find myself thinking about the process in which programmers learn to program, and eventually become engineers. I look at sites like “The Daily Worse Than Failure” and compare them to my own development as a Software Engineer, and I am forced to realize that most programmers do not have a clue why their code is bad. Or they may even know their code is bad, but do not know how to make it better.

The ability to understand how to make better code comes with an awful lot of sweat and a little bit of luck. Books on the subject are becoming more readily available. However, they are not accessible to the person who has the most to gain from understanding their topics: the extreme beginner. The person who wishes to know “how to program” does not have the tools readily available to understand the concepts, principles and practices needed for good design. Yet, the person who wishes to learn how to program has most benefit from these concepts, principles and practices. It's best to get it right the first time rather than having to struggle with shaping the already learned concepts into those that a good programmer needs.

The standard education of the beginner programmer starts either with a class or a book, where they learn the rudimentary aspects of a particular language. In so doing they learn very bad examples of what objects are, and how to use that language to fulfill the requirements of being object orientated. They are given examples to follow to solve specific problem areas. These examples are usually poorly written with the intent to explain language features rather than good OO Design.

Agile has an improved method. Take junior programmers and pair them up with several more advanced programmers. The junior will pick up good design as if by osmosis. Agile proponents tend to mention this aspect of pair programming as one of the top benefits of the methodology.

That being said, beginner programmers are not junior programmers, and can seldom get a job where they can pair up and learn. Also, they seldom have the available resources of advance programmers to learn from. There has to be a better way to get good code onto production sooner.

I am thinking turning software education on its head. The old thought process was that a person has to understand how to use a programming language before they could understand some of the more abstract concepts like refactoring and design patterns. I also argue that a person needs to understand refactoring and design patterns to understand programming. So it would appear the programming world is stuck with a “Catch 22”.

I believe it is possible to introduce the rudimentary aspects of a language, followed by refactoring and then patterns in such an iterative way that the student can learn how to be a good programmer and not just a code monkey. The process would seem to take longer at the onset, but would produce a stronger programmer more quickly.

Legacy code and Characterization

2008-02-07T17:49:00.000-08:00

Introduction

I have had the enjoyment lately of maintaining my own legacy code. This is surely a humbling experience. It makes you realize how much you are not a hotshot engineer, but a simple code monkey living in a planet of apes. Now looking forward I am using this experience to learn, grow and never do that again.

In my search for the question of how do I maintain the tangled ball of classes I had written, I have come to a number of tools. The first is a god send of a book “Working Effectively with Legacy Code” by Michael Feathers. The second was NMock2.

The book gave me the mental toolset I needed to safely refactor my code, and NMock2 gave me a utility that I could use to characterize what my code did.

I will start with Michael Feather’s definition of legacy code. He defines legacy code as any code which is not protected from unintentional change by Micro Tests.

Ok so what about characterization. Characterization is the understanding and description of a piece of code such that you can tell what it does. A characterization test (a term taken from Michael Feathers) is a test that determines and documents what a piece of code does. What this means is that since legacy code is not protected by micro tests, you can use a test to determine what code does and then verify that your changes do not change the behavior and result of the test, unless the change is the desired one.

Peeling the Onion
A technique I have discovered for getting my legacy code under test is very much like peeling away the layers of an onion, until I have two desired results. I want the code isolated, so it can be accurately tested, and I want tests in place that exercise 80% or more of the code where I am going to make my change.

There are a few rules I follow when doing this.

I am disconnected from all external systems

This can be as simple as removing the connection string from a configuration file to unplugging my machine from the network.
The point is that I force isolation to allow me to find dependencies.

All parameter values are useless until I see otherwise.

Here I pass null or empty default values into a parameter until I either get an error or some output from my code that shows use of the default. Then I put in a unique value that I can track through the code.

All out puts are default empty values unless I see otherwise.

The point here is I never look into my code to figure out what is supposed to be returned. I simply assert that the return is empty or null, and when it fails, change the Assert until it is correct.

All failures that happen outside of the code under test do not matter.

Here I follow the stack trace of all failures only as deep as my code under test. This tells me where there is a dependency to break.

When an exception is raised, I open the code under test at the point where the exception was raised. I then start refactoring. I use only very small and safe refactorings. And then I retest my code verifying I get the same error in the same place. This shows me I have not changed behavior of my code thus far.

Once my code is in a shape where I can remove the dependency that threw the error, I remove it and replace it, in my test, with a mock object. This allows me to document and verify behavior of the code.

I continue doing this until the test passes. I then do state checking of any out puts that are received from the code under test, and refactor the tests so they are easier to read.

I then copy the test and change a default value and see if the test changes behavior or output. If it does I continue until it passes and then start over. If it doesn’t, I undue my change and change something else.

If no changes change behavior or out puts I examine the code under test and see if there are any “interesting” branches that are not being exercised. I then alter inputs to exercise that branch.

I do this until the code has enough coverage for me to feel safe making my change.

Now we have all the code under test, I change tests or write a new test to reflect the changes which lead me to start this process. I rerun my tests and verify there are now the failures I expect. I then make my changes, run all my tests. If all goes well I have no failing test. If any tests fail I investigate and understand what I did.