I’ve been thinking for awhile now about this post and I’ve been unsure of exactly what needs to be here.  I know I’ve done a lot of maintenance work.  It’s inevitable.  You name the field and chances are we’ve developed something for it.  A lot of the software we develop we do so because there just isn’t commercial off the shelf (COTS) software for the business process.  COTS is for the broad market.  So customers come to us when COTS doesn’t meet their needs.

Which gets us to maintenance.  We try the best we can but in any software application there will be bugs.  It is inevitable, it is a fact of life.  Unless you are just writing a “Hello World” program there will be people who use your product in ways you didn’t expect.  We have had clients who take the application we’ve written for them and walk away.  Not because they’re unhappy but because the cost to fix every single bug and add in every feature they want can often be prohibitive.  They’re happy where the app is and that’s good enough.

Most clients stay with us for a maintenance tail.  They prioritize the bugs they want fixed and features they want added and budget accordingly.  We want happy clients, it’s that simple.  The happier they are with us the more work they bring to us.  This is common across all businesses, whether you’re a dry-cleaner or doing software services, a happy client is good.

So in software services how do you make a client happy?  In my experience it’s been minimizing maintenance tail costs.  But how do you do this?  I’m going to try and sum up where I have noticed problems.  I could reprint Code Complete here and say, “There, that’s how you do it” but that would be meaningless.  The point of this post is to focus on a few key points.

1.  The obvious:  Requirements, requirements, requirements.
As much as possible try to impress upon your clients the importance of requirements.  The more requirements analysis and design that is done up front before even beginning development the cheaper the maintenance tail.  It’s fact the earlier you find a problem the cheaper it is to fix. (Code Complete, Table 3-1, Average Cost of Fixing Defects Based on When They’re Introduced and Detected)

The biggest problem with this?  Most of the time clients don’t know what they want.  That’s right, they come to us and say, “Well, I want an application that does this.”  But what does that mean?  Does this need to mirror an existing business process?  Is it something completely new?  Do you have an idea of how the process should flow?  Do you know where you get your data and where it should go?  What kind of reporting are you going to need? (Customers never know that last one)

A lot of time we end up building up an existing business process in order to understand what needs to be developed for the application.  That’s okay.  I can accept that business analysis may be a part of the job.  So this is key:  (most of the time)  Clients don’t know what they want.  They will usually have a generally vague idea but you will have to help them.  Try to come up with a basic set of requirements.  Next, at a minimum, whip out Visio (there are better products out there but Visio is probably the most common) and throw together a few pages of the app.  Put together some sort of flow.  Help them bring their vision to reality.  Only then will they really begin to understand their own requirements and process.  Only then will they see what’s there and what’s missing.  Most clients can’t envision software.  They’re paying money for something that is completely virtual and just can’t see the final product.

Now, this is all well and good.  The problem is that a lot of clients don’t want to spend several weeks (or longer) designing the app, they want to get moving on it.  This leads to iterative development.  It’s more expensive.  But done properly I’ve still had happy clients.  Prioritize parts of the application.  Model a couple of those pages, build it, move on.  You will have problems.  I had one client who missed telling us about a key part of data for the app.  The ERD we had didn’t support this new data so we had to build out some new tables and fix everything.  This was after we’d done requirements and modeled the pages.  It wasn’t until the app was in beta that he went, “Oh, and you need to put this in there.”

2.  Naming Conventions: Use it, love it
This is going to sound stupid but one of the biggest problems I’ve had coming in to maintain an app I didn’t design or build is naming conventions.  Even if the names are consistent and meaningful, when there is no standard across an application where multiple developers have been working on it, it takes way too long to understand everything.  I’m not saying that your company should enact a strict naming convention company wide.  That would be nice but it’s not reality.  Your project lead, however, should.  Even if you’re working under different project leads you need to adapt.  This is especially true in this polyglot world of development.  At one time I was working on a PHP project, a java project and a C# project.  Each has their own naming conventions.  Yes, it took longer when I had to switch projects to re-orient myself but that in and of itself is the nature of polyglot programming.  I know that when someone comes behind me to maintain the app (and in a lot of cases it’s even me) it is a hell of a lot easier to get going on maintenance when there is some sort of naming convention across the app.

So what do I mean by naming conventions?  Method names, event and delegate names, variable names.  If it takes a name there needs to be a standard.  Whether it’s public, private, static, constant, an enum or class, there needs to be a standard.  The only place I haven’t seen a need for naming conventions is internal to methods.  If the app is coded right and adhering to basic OOP methodology variables internal to a method shouldn’t be around that long.  They still should be meaningful but I don’t care if you want to put an underscore in front of your internal variables or not.  I don’t care if you want to capitalize them or not.  Anytime I have to walk through from class to method to class to method to delegate to method there better be some sort of convention.  Otherwise it costs the client money.  There will always be some sort of spin-up when entering maintenance.  Just try and minimize it.

So you’ve got your requirements and naming conventions, what’s next?

3.  OOP, if you use it, use it
The biggest trouble I’ve had, excepting those mentioned above, are projects where developers seemed to take a procedural approach to OOP.  God classes and methods (functions?), poor use of inheritance and virtually no use of interfaces.  This makes maintenance tough.  I have to admit I myself was bit lacking in this area out of college.  Sure I took an OOP class, sure I had the theory but applying the theory is wholly different then having the theory.  And I’m not the only one.  It seems one of the universal constants having new engineers on my team fresh out of college is that they can’t apply OOP.  This often also applies to self-taught programmers who many times don’t even have the theory.

I want a black box (Code Complete, Encapsulate Implementation Details, Information Hiding).  When I step into a method during troubleshooting I want to only go into that method once.  There after I want to trust that the method works as intended.  I want a method to only do one thing and not affect parts outside of itself.  If I have a login control it should only be doing login.  I want a class to default all properties (getters/setters) to private.  I don’t want those variables being changed outside the class unless they need to be.  I want interfaces(Code Complete, Form Consistent Abstractions).  It seems like this is the least understood by programmers straight out of college.  So often new engineers like to inherit and override.  Obviously this has it’s time and place.  But think if this really is needed or if you just need to create an interface (Code Complete, Inherit-When Inheritance Simplifies the Design).

I digress, I’m starting to write out Code Complete.  If nothing else, use and apply Code Complete, 5.3 Design Building Blocks: Heuristics.

So how to fix this?  If you have an engineer on your team that you’re not familiar with do a code review.  Assign him a task and take a look at his code.  I don’t think I carry the title Senior Software Engineer because I such a great programmer.  Really I barely consider myself adequate.  I have seen a lot of code, written a lot myself, I lead teams pretty well as a project lead and clients like to work with me.  If you’re leading a project remember the code of the engineers underneath you is your responsibility.  Yeah, you might ruffle some feathers.  We programmers take our code personally.  We’re proud of it.  No different than an architect whose proud of a house he’s built or a chef whose proud of his food.

4.  Stay up-to-date
I won’t harp on this long because I’ve said this before.  Programmers use what’s available to them.  I love LINQ, but I know LINQ because I read about it before it was even released publicly.  I can do a lot of stuff easier with LINQ.  I love WPF, but I know WPF because I read about it before it was even released publicly.  I can do a lot of stuff easier with WPF then I could with WinForms.  If you don’t stay current there’s a good chance you’ll jump into a project where it’s using something you don’t understand.

5.  Code to maintain
I suppose this is really the heart of the issue.  What the hell does this mean?  Any adequate programmer should be able to jump into a piece of code and start working on bugs and adding features.  I’m not saying there won’t be a spin-up.  Of course there is going to be some spin-up.  But try and minimize that.  When most people are working on code they’re not thinking that in a year or more someone is going to have to come behind them and read the same code trying to figure out what they were doing.  But they should be.

Finally, I want happy clients.  That means minimizing maintenance.  There will always be maintenance, it’s inevitable.  But when I can jump into the maintenance tail of an project faster, fix bugs faster, implement new features faster than clients are happier and my job is easier.  And I like it when my job is easier.  It will always be challenging but I prefer challenging and fun to challenging and a pain in my ass.

I could keep going.  Someone could write a book on the subject (yeah, I know, Code Complete).  This post is just intended to hit a few top issues I’ve seen when maintaining code. YMMV.  You may have seen other issues that top this list.  Tell me about them.  Post a comment.

Later,
Brian

Let me start off by saying I’m excited that I finished it. There is a lot of good information and there is no doubt that it is the standard for sound software developement principles. That being said, remember when you try to tackle this bood that it is a text book. Sure there are some interesting anecdotes about this and that. I suppose I should have been more thrilled about reading it but couldn’t drag myself to pour through it like I have some of my other software books. It took me a year to read Code Complete. During that time I re-read The Belgariad series, The Malloreon series, most of the Song of Ice and Fire series, and read for the first time Pro WPF in C# 2008, Effective C# and I’m almost done with More Effective C#.

So what am I saying? I know there are those of you out there that love Code Complete and read it voraciously like a good fiction novel. I couldn’t even read it like a good code book. Pro WPF in C# 2008 I read like a good fiction novel. I drank it in and loved it. Code Complete I just couldn’t do that with. As I said, it’s sound, solid developement principles I try to apply every day on the job. I learned a lot and will continue to try and apply the princibles of Code Complete. Simply because of that it is a reason to read the book.

If you’re like me and are struggling to get through Code Complete, spread it out, read a chapter and then take a break and read something else. There are 35 chapters in Code Complete. Read a chapter every two weeks, in between other books and it will take you just a bit over a year to read it.

What else can I say? 99% of the book makes perfect sense. Some of the code formatting seemed a bit off but I just let visual studio format my code for me. Ctrl-K + Ctrl-D, Baby!

Read it, grok it, follow it and your code will be better, cleaner and easier to maintain.
That’s all there it to it.

Brian

2009 CWE/SANS Top 25 Most Dangerous Programming Errors (If it doesn’t come up be patient. It looks like the server is getting hit pretty hard with bloggers like myself linking to it.)

Or read a summary of it and then go to the link over at Coding Horror.

On a side note, now that the holidays have calmed down I’ve been working on a series of “Often Unused Operators” like ~ and |=. Credit goes to Jeff Clark for turning me onto this. Hopefully I’ll have the first one up on Friday.

Brian

string x = "";
x = "asdf";

what you are really doing is creating two different strings, not changing the value, per se, of x but actually creating a new x.
That is why in heavy string opperations it is recommended you use StringBuilder like:

StringBuilder sbName = new StringBuilder();
sbName.Append("asdf");

since appending to sbName doesn’t create a new string but continues to add to the string value of sbName.

So why do you care? Well, maybe you don’t. I’ve started to move into a more multi-threaded world where the state of objects and their properties could potientially be invalid if an external thread changes the value of a property. I’ve been reading Effective C# and More Effective C# and enjoying them. They are books that target specific development issues and paradigms that help you become a better C# developer. The books are written by Bill Wagner who is a regular blogger I follow.

Even though Effective C# came out in the .NET 2.0 days alot of the book is still relevant, however, quite a few of the code samples could be updated.

Item 7 in Effective C# says “Prefer Immutable Atomic Value Types”. Now to paraphrase the chapter to an extreme it basically says, “Immutable code is easier to maintain”. I would add an addendum that whether you like it or not there is a good chance that code you write will be used in a multi-threaded environment and immutable will matter.

Now obviously to blindly say all classes must be like this is absurd. As Bill’s Item 7 says, however, “Prefer Immutable Atomic Value Types”.

In .NET 3.0 properties made things a bit easier in general. Prior to 3.0 for a property you would have to do:

private int _myInt;
public int MyInt
{
    get { return _myInt; }
    set { _myInt = value; }
}

In .NET 3.0 you don’t have to define the private. When the code is compiled it will take care of that for you. So the above code becomes:

public int MyInt { get; set; }

Now say you have to class:

public class Customer
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public Address Address { get; set; }
    public Customer(){}
}

If you were working in a multi-threaded environment you might have a problem if this happens:

public void HandleCustomerData(Customer MyCustomer)
{
    MyCustomer.FirstName = "George";

    //use myCustomer to do a bunch of stuff

    MyCustomer.FirstName = "Joe";

    //use myCustomer to do a bunch of stuff
}

This could cause a big problem if MyCustomer is getting passed around alot in different threads. Now I know this is rather contrived but it is still a real issue.

Properties an additional feature here in 3.0 that makes things easier for creating an immutable. Imagine you have to class:

public class Customer
{
    public string FirstName { get; private set; }
    public string LastName { get; private set; }
    public Address Address { get; private set; }
    public Customer(string FirstName, string LastName, Address Address)
    {
        this.FirstName = FirstName;
        this.LastName = LastName;
        this.Address = Address;
    }
}

You can see here that I’m using the private keyword on the set method. As it implies this forces the set methods of the properties to private so they can only be changed internally in the class. I would recommend reading “Effective C#” for a better explanation of why to use immutable values but by using the private in a property this becomes easier.

So there it is, prefer immutable atomic values in your classes and use the private keyword to help you.

Later,
Brian

Update:
The more I read this the more I think I over-simplified Bill’s reason for prefering immutable atomic value types. Just get the book and read it. It’s a fairly small book but every nugget has value.

None of us use Asserts enough. It’s that simple, we don’t. Asserts are essentially a way to ensure we don’t get a value we shouldn’t have. The great thing about using asserts is that they aren’t included in final code (compiled in “Release”), only code complied with “Debug”. They make testing easier by verifying that when code is being tested in Debug that it doesn’t go beyond some condition. They can also be used to ensure when troubleshooting that you have the values you should.

Take a look at the code below:

private void pass_Click(object sender, RoutedEventArgs e)
{
    int temp = 1;
    Debug.Assert(temp > 0);
    MessageBox.Show(“Pass”);
}

private void fail_Click(object sender, RoutedEventArgs e)
{
    int temp = -1;
    Debug.Assert(temp > 0);
    MessageBox.Show(“Fail”);
}

This is a sample of using an assert. I know the example is trivial but I wanted to show a simple use of it. These are simply a Click event on a “Pass” button and a Click event on a “Fail” button. I would recommend you create your own solution and put these on a pass and fail button so you can see and understand what happens when Debug.Assert is called.

Now lately I’ve been coming across a lot of code like (anonymous-ized for your protection):

I’m sorry but this is simply wrong.

Code Complete 2nd edition has a great chapter on Assertions. The above example is exactly where asserts should be used.

Per the guidelines for “Using Assertions” (McConnnel, Code Complete 2, 2004) the following guidelines should apply for using assertions:

“Use error-handling code for conditions you expect to occur; use assertions for conditions that should never occur.

Avoid putting executable code into assertions.

Use assertions to document and verify preconditions and post conditions.

For highly robust code, assert and then handle the error anyway.”

That’s right. The very first usage guideline says to use asserts for conditions that should never occur.

Take a look at a sample from Code Complete (originally VB but I ported it to C#):

On this McConnell has to say:
“If the variables Latitude, Longitude, and Elevation were coming from an external source, invalid values should be checked and handled by error-handling code rather then by assertions. If the variables are coming from a trusted, internal source, however, and the routine’s design is based on the assumption that these values will be withn their valid ranges, then assertions are appropriate.” (McConnell, 2004)

Now assertions aren’t the end-all, be-all of validating values. Chances are that in most cases you are still going to want to validate and do error checking. But they’re a good start.

And just for the java folks that hung around, an assert in java:

Refs:

Code Complete (Second Edition), Microsoft Press, Steve McConnell, 2004

C# Online.NET – Assert

Debug.Assert Method

And just for the java folks:
Programming With Assertions