Brendan Enrick

Daily Software Development

2014 Software Craftsmanship Calendar

The 2014 Software Craftsmanship Calendar is now available for preorder!

If you were a fan of any of the previous Software Craftsmanship Calendars or just liked the posts about some of the months, you'll be glad to know that we continued making a new one. We are continuing to alternate between Good Practices and Bad Practices, so this year (being the 4th) is a calendar of anti-patterns.

Each month of this calendar shows something that you shouldn't do, but plays it off as a good thing. You'll also find an interesting, related quote and a definition of the anti-pattern on each month.

Go get your calendar today!

Duct Tape Coder

For anyone following along in the NimblePros Software Craftsmanship Anti-patterns Calendar, June is the month of the Duct Tape Coder. The calendar is a great reminder to try to avoid all of these bad practices. You obviously want to avoid all of the bad practices illustrated in the calendar, but for the month of June, you should be focusing on not being a Duct Tape Coder.

Duct Tape Coding

Similar to Cowboy Coding, Duct Tape Coding is all about getting things done. Not worrying about how you do it or how it will be maintained in the future. The goal of the duct tape coder is to get something working.

You might be saying to yourself, “I thought that all of these agile good practices said to start with the simplest thing that works!”

You’re correct. It says to start there. That means that you need to clean things up and use refactoring to create a maintainable, clean solution. Consider the initial duct tape to be scaffolding to allow you to build the final, maintainable solution. The duct tape, along with some automated tests allows you to build a system to be proud of.

DuctTapeCoder

Spend June making sure that you’re building your software the right way. Don’t settle for a “working” solution. Build a good solution.

Try Writing Try Methods

When I say "Try Methods", I am of course referring to the common prefix "Try" on a method, which implies that the method is going to attempt to do what you're asking by using an output parameter for the operation and using the return value to indicate whether the attempt succeeded.

The common ones that people see in the .NET Framework are the TryParse methods, which attempt to parse something and if it can't be parse, they assign the default value to the output parameter and return false. If the succeed, the parsed value will be placed in the output parameter and the return value will be true. If the code failed, the convention is to use the type’s default value to assign to the output parameter. This lets you write code like this:

int someNumber;
int.TryParse(userInput, out someNumber);
// use the number entered or the default 0
int result = 1 + someNumber;

 

This is also great when you're going to be checking whether the method succeeded. In fact, you can use the try method directly in the if block, which usually makes things nice and clean. Here is an example of using them like that:

int someNumber;
if (int.TryParse(userInput, out someNumber))
{
    // Do something with someNumber
}
else
{
    // Invalid input: handle this case accordingly
}

 

Yes, you know all of this and have seen it before, however, are you writing these types of methods yourself or is your only experience with them the standard TryParse ones?

What I am trying to emphasize here is that you need to write your own Try methods in your code. You will thank yourself later.

Everyone can see the obvious benefit of not having to check for the default value to see if it the method worked. You also don't have to have ugly Try-Catch logic in your code. You get an if statement instead.

The real benefit of a writing a Try method has nothing to do with what I've already said. The most important benefit, in my opinion, is that you have a return value from it that isn't the value you are using for your logic. By having this return value for its success, you have to decide on how to handle the case where it failed.

There are important cases that might be forgotten, but having a return value means that I need to handle the return value. When I have it, I need to decide what to do with it. There may be a message I need to display to a user. There may be logging I need to do. I might be able to ignore that case. What is important, however, is that I thought about how to handle it. I had the chance to make sure that I handled the case correctly.

Create your own “Try” methods. I recommend looking into creating your own “TryParse”, “TryGet”, TryDelete”, and anything else that has a chance of failure that you may want to handle.

Good Teams Focus on the Team

I believe there are two main types of “teams”: those working together, focusing on doing their best as a team and those working individually, focusing on doing their best on their own. (Yes, some teams are in between.)

I think you can guess based on my wording of those two options, that I prefer working as a team toward a combined goal. By working together, we can accomplish much more. We must be careful along the way, however, to make sure that we don’t do anything that can hurt the teams abilities to work as a team.

Building a good, cohesive team is my greatest achievement in my software development career. Being a part of this team as it achieves great things is what I have received in return. – Brendan Enrick (March, 19, 2012)

I am always trying to make sure that the team is doing well. I try to keep them focused and working together. Most of all, I try to make sure that the things I do don’t hurt the team. It’s important to recognize that decisions and choices we make affect the team a great deal.

Building strong teams requires a lot of work. This post focuses on considerations that I believe are important to creating strong teams. These considerations include: communication, co-location, combined interest, respect, and commitment consensus. I focus on these when trying to create good, cohesive teams.

Communication

Creating great software depends heavily on communication. This is important for the whole team. It’s important that all members of the team be communicating with all other members of the team. If communication breaks down, the team is soon to follow.

It’s important for the whole team to be talking, writing, documenting, and sharing their ideas. Make sure that your team feels safe working together and communicating with each other.

Communication is so obvious as an important aspect of a good team, that I am not going to spend a great deal of time discussing it.

Co-location

There is no easier way of getting a team to work together than to have them located together. Keeping the team close together keeps communication high. Not only does this mean that asked questions will be answered quickly, it also means that questions will be asked. If the team were not together, someone might not have asked the question. This keeps the communication barrier low and the feedback loop short.

I said this was an easy thing to achieve, and it can be. Sometimes there are difficulties with logistics of your space, people not wanting to move, etc. These can happen and can also be worked through. If you don’t have a team room, you can still set up a “command center” in an unused conference room.

I’ve seen both introverts and extroverts do well in co-located teams. When the conversation is on-topic it allows everyone to tune in to what the team is doing. The team will start answering questions immediately, knowing what everyone else is working on, chiming in with assistance on an area of expertise.

Great teams work together

Combined Interests and Goals

It’s extremely important that a team have a shared goal. If you fragment the goals of your “team”, you will be fragmenting the “team”. You run the risk that the team will have no incentive to work together. Yes, you might say that since everyone gets along, they’ll work together still, but you’re driving in a wedge that will pull them apart.

I don’t want my team to have individual goals, this will cause them to work on their own and make it harder for them to work together. Anyone spending their time helping someone else would be in danger of not finishing their own work, but I want them working together to achieve more.

Nothing is as detrimental to a team than making them behave less like a team.

By combining the goals and interests of the team, you force them to work together. They get the idea that they’re being graded together and being rewarded together. This will keep everyone on the team at  their most productive, because they will all have each other to lean on.

Respect

This word gets four uses here. It is important that members of a team treat each other with respect, it is important that members of a team respect each other, it is important that each member respects oneself, and it is important that everyone respect the code being written.

If one member of the team doesn’t respect another of the team members, the team will not be cohesive. If one member of the team doesn’t show respect to one or more members of the team, the team will not be cohesive.

If one member of the team doesn’t respect oneself, the team will not be cohesive. If one member of the team doesn’t respect the code being written, the team will not be cohesive.

When the team has respect for each other, they will strive to not hinder the rest of the team. This means that they will try not to break the code base. They will try to make sure that they build good, simple designs that everyone can appreciate. And communication will also flourish.

When the team has respect for themselves and the code they’re writing, they will strive to write clean, simple, well-tested code. The team will care about the work they’re doing and will avoid creating a big messy codebase.

Commitment Consensus

Making any commitment as a team must be done with a consensus among the group. One of the worst things that can be done to a team is to set their commitments for them. You can’t tell someone else what they are required to commit to.

Commitments have to be made willingly or the commitment might as well not be made at all.

This mistake is commonly made by people assigning work for the team to work on without getting their feedback on it. If you assume that a team can get X amount of work done without asking them, you’re asking for trouble. First, you’re making their decisions for them. This is going to make you into the opposition of the team. Second, you’re not soliciting their opinions or feedback.

Often this means that someone who is not going to be doing the work has estimated the time the work will take to complete and has assigned this work to individual team members. This will break the combined interest, encourage the team to break from their co-location, and cause the team to feel the person making those decisions isn’t taking them into consideration.

The right way is to work with the team. If you do need a commitment on something, you should work with the team to create that commitment. This usually means sitting down and working with them on it. Get them to decide what they can accomplish in an amount of time. Work with them to decide what will be worked on. This means that the person deciding the direction of the project should be directly talking with the development team doing the work.

Getting people together, working together, collaborating, is what makes teams effective. Don’t try to force them into doing something they don’t want to do. It will backfire on you. Plus, they’re likely not going to uphold that commitment. It wasn’t their commitment anyway. Not really.

The Team

If you manage to get the team working together effectively, keep it up. Try new things, but don’t let it destroy the team. If it looks like it’s hampering the team’s togetherness, quit doing it. Find another way of doing whatever you’re doing.

Don’t force the team into processes they don’t like. Let them create a process that works for them. Give them the tools and enable the team to make the right choices. Empower your team! Make sure that you never become the opposition of the team. Try to be part of the team. Align your interests with theirs.

Overusing Interfaces and Injection

In software development, it is very important to continually learn and experiment with new techniques for building great software. Our job is to learn and improve the quality of code that we build over time. It is through this progression of experimentation, failing, succeeding, observing, reading, listening, and teaching that we as developers improve. In this post, I am going to discuss one way in which we as developers have learned something great and have taken it to the point of failure. This will allow us to learn, resolve, create new techniques, and succeed in the future.

What is Dependency Inversion?

One of the most important SOLID principles for testing our applications is the Dependency Inversion principle. I am very glad to see many more codebases using this technique as time goes on, however, I am seeing nearly as many others getting caught up in an easy mistake of using too much injection and putting interfaces on everything regardless of necessity. Lets start by defining dependency inversion so we’re all on the same page.

From Wikipedia:

In object-oriented programming, the dependency inversion principle refers to a specific form of decoupling where conventional dependency relationships established from high-level, policy-setting modules to low-level, dependency modules are inverted (i.e. reversed) for the purpose of rendering high-level modules independent of the low-level module implementation details. The principle states:

A. High-level modules should not depend on low-level modules. Both should depend on abstractions.
B. Abstractions should not depend upon details. Details should depend upon abstractions.

Reading directly from this, we can see that it says we should be depending on abstractions and in doing so we take a much lighter dependency. A dependency on an abstraction is not a big deal. A dependency on a concrete class is a big deal.

Is what I just said always true? No, it depends on the abstraction and the concrete class. For example, I make an exception for simple classes provided through the framework or language my code is primarily based on. For instance, I have no problem saying that my method depends on being given a DateTime object since there is no real gain by abstracting that object since that is a part of the framework and I will always be injecting in an object of that type.

When are interfaces and injection being overused?

One example of over-architected injection that I see a lot comes from something that I’ve taught many times when explaining SOLID. It’s the classic example of a dependency that people don’t realize they have.

DateTime.Today

I assume most of my readers know that this is a dependency taken directly on the system clock. It’s important to inject this dependency when your code behaves differently based on the value returned from that static method. When we extract that dependency, people have been taught (by many people including me) that a good way of testing this is to have some kind of IClock interface with an implementation of SystemClock accessing the computers clock by calling that static method we were just discussing.

Now when we write our method, we just give it a parameter of IClock. When we run our code in production, it’s taking in the SystemClock object, and in our tests we’re using a mock object. Great! We’ve reversed the dependency! Is that really what we wanted though? It might have been, but in some cases we could have just passed in the DateTime instance object returned from that method. This would have reduced complexity in our code.

Because we used this interface instead of just depending on simple concrete classes, we’ve actually made our code more difficult to use and maintain. Isn’t that the whole reason we were following SOLID in the first place? Yes, yes it is. This is of course a simple example, but you can find larger examples of where you could test your code and build in a nice structure without having to create pointless interfaces. Heck even in this example, you might have a good reason to need that Interface, but I am sure that you could get away with using it less. Every time you add that layer, you add complexity. Sometimes adding it is OK, because it gives you a much needed seam, but I doubt you need it as often as you think.

Please make sure that you need the interfaces and layers of abstraction before creating them. I’ve come across many codebases that become as complex or more simply by trying to do things “the right way”.

The road to software development hell is paved with good intentions.

 

Don’t like the way I phrased something? Think I overgeneralized? Did I make a mistake?

Call me out on it!

I appreciate the feedback.

Overmocking

One of the most powerful tool available to developers testing a legacy code base is the ability to mock out classes that their code depends on. This is of great importance since our unit tests need to limit the scope, and we do this by trying to limit our dependencies. Through mocking we can exchange one dependency on the infrastructure of our application for an in-memory mock.

Sometimes mocking is overused, and I am not just talking about cases where every objected gets mocked to the point where we’re testing nothing. I am talking about a different issue in mocking. I am talking about where developers put on their mocking blinders when unit testing. It’s an easy thing to do, and I’ve done it plenty of times myself.

Setting Up Our Example

We will start of by defining our example. We will have a method to do some sort of calculation (an ideal and easy testing scenario). It will be a legacy code base, which means that it is untested code and probably hard to test. We’ll start off by making it a private static method and put in a nice dependency that one might try to mock to avoid.

private static decimal CalculateFooOnXyz(Xyz xyzItem, 
decimal calculationParameter1)
{
var numbersInCalculation = Repository.GetNumbers()
.Where(n => n.IsActive);

foreach (Number number in numbersInCalculation)
{
// Some code that executes for each one.
}
}

Now that we have this method, which is scary and really needs some testing we’ll take a look at the simple way of testing it; we will use parameter injection to pass in the dependency since we’re static we not easily able to do any other safe forms of dependency injection. When we do this, we end up with the following code.
 
private static decimal CalculateFooOnXyz(Xyz xyzItem, 
decimal calculationParameter1, IRepository repository)
{
var numbersInCalculation = repository.GetNumbers()
.Where(n => n.IsActive);

foreach (Number number in numbersInCalculation)
{
// Some code that executes for each one.
}
}

This is a pretty simple change. We now mock out the repository and pass in the mock in our test and we tell it instead to return the collection we specify in memory instead of requesting the data from the database.

Why This is Wrong

My first question is, what is the name of the method? CalculateFooOnXyz. Notice that I didn’t say, “GetDataFromTheDatabase”. That’s because we shouldn’t be doing that. It isn’t part of the calculation. The numbers returned from the database are required for calculating, so that means that we should have that object as our dependency instead.

How We Change It

So instead of making the repository our parameter, we should make the collection of numbers our parameter. This way we’re depending on the in-memory collection of CLR objects. This is much less of a dependency, and in is not one that needs to be mocked. By doing this alternative we’re better following the Single Responsibility and Dependency Inversion principles.

Our best code for testing will look like this.

private static decimal CalculateFooOnXyz(Xyz xyzItem, 
decimal calculationParameter1, List<CalcNumbers> numbersInCalculation)
{
foreach (Number number in numbersInCalculation)
{
// Some code that executes for each one.
}
}

Comments? Have a better way of doing it? Did I make a mistake?

Commenting Methods Using Liskov Substitution Principle

After reading the title of this post, some people might be wondering why I am advocating commenting at all, because I’ve spoken out against commenting code before. My team and I were recently reading through some code that was littered with comments, and I do mean littered. There were tons, they were mostly useless statements like “//run”, and I swear there were more of them than actual code. This of course sparked some preaching to our choir about how comments in code are often less-than-useful. We of course settled on the time when they are useful being the XML comments on methods, but those should also only be used when writing public libraries where others will not have access to the source code or unit tests.

Comments on those methods are useful since tons of people will use the method and will not be able to see the guts of the method or examples of how to use it. This makes the comments useful. However, they need to be kept up-to-date (difficult task).

So what does all of this have to do with Listkov Substitution? Well, the principle basically says that all of the classes which implement an interface (or inherit) need to work the same way. There should be no difference between implementations as far as the calling code is concerned. In fact it is really about making sure that we maintain a consistent abstraction. If we say something about the interface it must hold true for the implementation. This means that any comments about the interface must hold true for every implementation.

We were wondering if the comments needed to be on each of the concrete classes or if we could just put it on the interface, and this was confirmed for me by Ben Heimann who quickly made an interface and a concrete class. Then he commented just the interface method and not the concrete one. We of course knew we would see the comment when using the interface, but we also saw it when we were dealing with the concrete class. Great work Visual Studio 2010! This means we don’t have to duplicate and also signals that we should follow LSP.

The concern is that if you have the comment in both places you would have to update them both. This also means that they could differ, and if they ever needed to intentionally differ then it means that we are violating LSP. Having the comment in the one place should at least point to the fact that we should maintain the same behavior for the calling code in all implementations of our interfaces.

Combining Object Oriented Principles, Practices, and Patterns

Now that the dust has settled from the recent Software Engineering 101 event we put on in Cleveland, I figured I would repost some of the material I talked about. This means some of connections that I vocalized and supplement the material from the slides I used for Software Engineering 101.

Object Oriented Principles, Practices, and Patterns

My first talk of the day was on Object Oriented Principles, Practices, and Patterns in which I start by discussing some common principles of object oriented programming: abstraction, encapsulation, inheritance, polymorphism, and I added composition in for good measure, which of course isn’t on its own a principle, but I feel deserves to be mentioned as its own entity at that point.

I covered an assortment of good practices for software developers to follow. Since Steve Smith was following my talk with one on SOLID, so I didn’t take the opportunity to discuss the Open/Closed Principle, which states that your code should be open to extension and closed to modification. This means that you can add to the behavior of your code by adding new code and not modifying what you already have.

In my patterns section I covered two of my favorite design patterns: the Strategy Pattern and the Template Method Pattern. These two are great for discussing with people. They’re very similar yet very different; one encapsulates the structure of an algorithm and allows for modification of the details of the steps while the other focuses on allowing for different algorithms to be used interchangeably. Each uses polymorphism, abstraction, encapsulation, and inheritance. They’re simple to explain and demonstrate, and they’re also very powerful. This makes them great examples.

 

Combining Everything

When we combine these principles and some design patterns we can achieve some great things. The strategy pattern is one of my favorite patterns, because it is very useful and improves maintainability greatly. I use it often. It uses, abstraction, encapsulation, composition, polymorphism, and either inheritance or interface implementation. On top of that it also helps follow the Open/Closed Principle, increasing the ease for changing the behavior of an application when the requirements change.

In my talk I was asked a great question, “if I don’t know design patterns, how will I know what I don’t know.” In other words, how can you possibly select the correct design problem to solve a problem. I recommended reading learning plenty just so you’ll be more prepared. There are plenty of books, and you don’t always need “the best” solution. Usually a good solution to the problem is enough. Steve Smith chimed in with a great answer though, he suggested practicing coding katas, which will often solve problems using design patterns or at least good, worthwhile practices.

Keep Databases in Source Control

Well, sort of. Your database can be rather large, so you probably don’t want to actually have the database file in source control. I do think you should have your database in source control, but really just your schema. Remember in my post about keeping your binaries in source control I mentioned that it is important to be able to go back to any point in time for your application. This means the database will need to match as well. How can we allow ourselves to do that? Keep databases in source control.

We want to be storing the subset of SQL usually defined as the Data Definition Language. These are all of the statements that create tables, define columns, create indexes, and make any alterations to our database schema. There are plenty of ways to store these. In fact I recommend after reading this post that you attend a local user group and offer this topic as a discussion for an open space. We’ve done this topic at HudsonSC and you get to find out a lot about what solutions other teams are using and why they’re using them.

Why store the database in source control?

We get a few advantages here. This is not an exhaustive list, but it does include some good reasons for following this practice.

  • You can set up your project on any computer and have a local database to test against.
  • Always be able to rebuild your database if anything happens to it.
  • Go back to any point in time and be able to create the database.
  • Incrementally change things and be able to see what changes have been made at any point.

How can I store my database in source control?

There are plenty of ways in which you can store your database in source control. I’ve used a few different techniques for doing this. There are some tools which can help you do this. Keep in mind that you can build your own as well. They’re not very difficult to create.

I have used Visual Studio Database projects before. These are nice because they’re a full package for handling the changes. This is the heavyweight approach to managing your database changes. This keeps each table, index, key, view, stored procedure, etc. as its own file. This built-in Visual Studio system allows you to update the project and use the project to update database.

The lightweight approach is to make each change using a sql script. You can write the alter, create, and drop statements by hand and store each one in a file. This approach makes it harder to see how each table has changed over time, but gives a better view of what changes were made at what points in time. In order to deploy the database updates you’ll either need to write your own system or use a tool like Tarantino to keep track of the changes.

There are of course other tools for handling this situation. What tools are you using for managing your database?

Other considerations

You will probably also want to have some code which can fill your test database with data to be used for locally running your application. I recommend having this code be compiled code (not SQL scripts). The reason for this is so that you can have the compiler assist you in ensuring that the scripts aren’t out of date. You also want this to be part of your build process, so that no one can forget to update it. It should be run by your continuous integration server, so that the build will break if there are any issues.

This will also make updating your production database a lot easier since you will have stored scripts which define exactly which operations need to be performed in order to update your database according to the changes you’ve made.

Keep Binaries in Source Control

No, not all of them. Just the ones required for your build process. Doing this will make your life a lot easier. You want to reference all of your assemblies locally and keep them in source control. You also want all of your testing executables kept there. If you have anything extra your build process depends on make sure you include that as well. A great example is a post I did about building a library which uses OpenAccess on a build server. The build server of course doesn’t have OpenAccess installed. That would be crazy.

You get a lot of great benefits out of keeping these files local and in source control. Since libraries change infrequently, they will not require much source control storage space. This also means that when updating from source control you will rarely have to wait for an update. If you do have to wait you probably needed it anyway, and would have just been waiting on an Internet download instead.

Build Server Benefits

If you have a build server this will allow you to build your application without having to install your tools and libraries on the server. When the server gets the latest version of your project from your source control server, it will already have the current versions of all of your tools and libraries. This keeps things simple and easy to work with.

If you don’t go this route you will have to install everything on the build server and make sure that all of the paths still match. Ever dealt with the Program Files (x86) folder?

New Computer Benefits

Have a new developer joining the project or just a fresh install of Windows on your computer? Great! Now just go and find the 10 different libraries and tools that are required to build this project. Once you have those make sure that they’re in the correct folders… Wouldn’t that be annoying?

If you keep those tools in source control and always reference with relative paths, no one will have to hunt for all of the tools required for the build. If you were referencing libraries in their install locations you would have all kinds of problems if something installed in a bad place. For example I’ve seen libraries try to install in a user-specific directory. Yes, that is a worst case example, but it can happen.

Keep everything relative and you can move your code anywhere. I want to be able to copy everything in source control onto a freshly installed copy of Windows and have it build. If I can do that, I know the project has a good structure.

Old Versions of the Project

Ever want to go back to an old version of your project and look at something? I bet you had some trouble building if you’ve changed the versions of any libraries you’re using. If the specific version you need is with that code you never have to worry. At any snapshot in time the repository has the correct build scripts, libraries, tools, utilities, and source code. You’re all set to go back to any point in the history of the application and take a look.

You might be saying, “what if I have changed versions of my IDE?” It shouldn’t matter. If you’ve got build scripts in place you can use those to get that app running.

Some people try to keep track of which versions of which tools are used for which release of an application, but if you’ve got them in source control you don’t have to worry about it. Just get the version you want, and the required files come with it.

Now that’s what I call a clean, self-contained build.