Develop for Maintenance

One thing I always keep noticing is that people will develop things without even giving a thought to maintenance.  This somehow seems impolite to me.   I suffer from Coder Alzheimer's, which means I can't remember a thing I wrote after not seeing after three weeks. That is why I think about things like maintenance.  I am seeing all new code if I have been away from it for awhile!  Now that is not completely true, but imagine how it may be for the guy who has never seen your stuff.

Challenge: How Easy is Your Code to Run?

I bet you can't guess how many steps it takes to get your project code running from a blank slate! In fact I bet it takes more than five additional steps for you to get it running. Five additional steps besides getting the source.

Try this. First check in any changes that you need to get in.  Now I want you to blow away your local source files. Everything. Remove the database from your database server. Remove your web settings. Remove any files and folders you may need for processing that didn't go away with getting rid of your local source files. Go ahead, I'll wait. :D

  1. Now, pull everything back down from source control.
  2. Crack open Notepad.
  3. Completely set up to the point you can finally run the application locally.
  4. Document every step in Notepad. Save that as a readme.txt file.

How many additional steps did you need to take to be ready to go again? Were you right?

If it does take more than 10 additional steps, you have failed.  If any of them involve getting a file or creating a folder (something you could give them with source control), you have failed (unless that is automated through another file that is in source control). Permissions don't count as part of the steps.

Maintenance Task 1: Make Your Code Easy to Read

What I like to see when I crack open code are methods named in a way they they actually tell you what they do.  They are also no bigger than about 25 lines and do no more than one task each.  I like it to be so blindingly simple to read or understand that even non-technical people can look at my code and sort of understand what it is trying to accomplish.

Maintenance Task 2: Make Your Code Easy to Run Right From Source Control

I came onto a project a long time ago that it took me a couple of days just to get the thing to compile. Two days! Imagine how much money in lost productivity that was for the company! The other developers on the project never really thought about what would happen if they blew away everything locally and pulled down from source. So they had certain things that were not right. They also kept some things checked out because each of them had conflicts and didn't really think about how to make it relevant for all of them.

Please make sure to get everything into source that you would need to run the application.  This makes it easy for someone coming in to just download the source and be off and running. This will save your company money.  It makes it really great when someone who has never even seen a line of code of yours that may have to suddenly work on it to be able to have an easy experience getting your code from source and running it as fast as possible.  What does that mean? That means if you have a file you are picking up and processing when running an application, put one in source and check it in. Make sure it builds to the output folder.  You don't have to have it deploy to other environments, but you need to think about the guy who is developing it locally.

The other thing is don't ever, ever, ever put yourself in a situation in team development where people have to keep a config file checked out locally because you didn't use a relative path.  If the path is important to running the application, please make sure it is part of your (local) build process. That also means it should be in source control.  If there is a file that is important to your application, it needs to be in source control as well. 

Maintenance Task 3: Include a ReadMe File For Additional Setup Required After Getting Source

One thing I have seen that I really like is when I pull down open source projects and they come with readme.txt files that I can take a look at and instantly know what I need to do to get the darn thing running besides just getting the code. 

That file you created in the challenge?  Check that puppy into your project's source control, preferably at the top level.

If any of the steps in the readme file involve creating files or folders, remove them and/or find a way to automate them. Don't make me create a file in a certain way. Provide me one or the means to build one automatically. Otherwise you are making me think too much. Make it easy for me or I will think you are not really being thoughtful and polite.  I already have enough to think about having to fix something in code I may have never seen before.  Make it blindingly simple for me.

Challenge 2: Give it to Someone Else

Now give that readme.txt to someone and have them follow it. Someone that is not on your project or has used your code before. When they are done, can they run the application locally?  How long does it take them?  How many questions did they need to ask?  Do any changes need to be made to the file to make it easier to understand (or for missed steps)?

Do not give them anything other than the readme and point them to the location to get the source. If they ask for any thing else, you have failed. If they cannot get the code running by the instructions alone, you have failed.

Conclusion: Make it Super Simple

Why do I promote making your code easy to maintain?  Very simply.  What would that person do if they don't have anything other than the source? They may have no one to ask because it has been five years and you and the rest of your team has left the company. Or they have to put a fix into production in the next hour and no one is around that would be able to help them.  They have to make it happen. 

If you believe situations similar to these can't possibly happen, we can still be friends, but I regret to inform you that you are very wrong.  If you think you write perfect code that never breaks, you are also sadly confused. It is a gamble to continue believing that someone could get in and work with your code without verifying it.

The question that you should ask when you develop code is: "How long would it take someone who has never seen your project before to be off and running?"

<a href="http://technorati.com/claim/b58wqz24ma" rel="me">Technorati Profile</a>

Print | posted @ Wednesday, June 11, 2008 7:48 PM

Comments on this entry:

Gravatar # re: Develop for Maintenance
by Scott at 6/12/2008 10:38 AM

your comment controls are weirding me out man.
Gravatar # re: Develop for Maintenance
by Scott at 6/12/2008 10:39 AM

ok trying for the 4th time lol

Good post. This is one of those things that gets lumped into the "mechanics" of software development and gets often ignored in favor of just writing code.

To go from zero to build for me is as easy as getting the source and doign ctrl+shift+b (and its not a trivial solution, multiple projects, few hundred thousand lines of code). IF you have nUnit and Rhino Mocks in the right places. And also the third party image control we have. So brand new guy...not as easy. I need to work on that.

Installed third party dependencies are a real enemy of the one-step build from scratch. Got a good solution for those? Simple referenced libraries can go right in source tree (like a /tools folder with nunit.dll) but installed dependencies are a different story. Just know they exist, put them in the readme, and install them?
Gravatar # re: Develop for Maintenance
by Robz at 6/12/2008 6:48 PM

Yes, I agree that it can be a pain to get required 3rd party installed libraries.
In the requirements section of the readme.txt, I usually put what version of MbUnit is required (prolly should include a URL as well) to run unit tests. SQL Server is another thing I add to required installed items.

We tend to keep the DLLs for 3rd Party components in a /ThirdParty folder (personally I like /libs) with every project.

Although this isn't my current practice, anything that needs to be installed could be included here as well (within reason, I wouldn't put things that are huge in source). I don't know how that would affect pulling down the source and bloat, though. Hmmmm....
Gravatar # re: Develop for Maintenance
by Robz at 6/12/2008 6:51 PM

I don't know what the deal with comments is, I have heard that from multiple people. I have problems commenting with Firefox almost every time, but IE less so. I am part of the GeeksWithBlogs (GWB!) community, so I should prolly mention it to the admins...
Gravatar # re: Develop for Maintenance
by Mike Henke at 6/15/2008 7:09 PM

I found Mylyn helps with Coder Alzheimer's. http://www.eclipse.org/mylyn/
Gravatar # re: Develop for Maintenance
by Scott at 6/28/2008 10:28 PM

So, had a chance to put this to the test this week. New developer started on monday. Also on monday I switched us from TFS to SVN.

Fresh svn update to full build for the new guy was about 30-40 minutes. It was pain.

The #1 problem was a couple of third party dependencies. We had our own external dependencies GACed with an installer, so that was fine, then we had things like rhino and nunit and a couple of others in source in a /tools folder off trunk, so that was fine, but there was one in particular that refused to be used without a full, licensed install. He couldn't even build with the trial version. We spent considerable time on that piece trying to get it to work before we just said "screw it" and bought him a license.

Without that piece, it would have been about 10-15 minutes just to run various installers, but the build would have been first try.
Gravatar # re: Develop for Maintenance
by Robz at 6/30/2008 11:19 AM

10-15 minutes is not bad. If all of the external tools had already been installed, what time would you have been looking at?
Gravatar # re: Develop for Maintenance
by Scott at 7/1/2008 12:42 AM

If every external dependency were preinstalled, it would have been SVN Update - > Build. So however long that takes, ~3 minutes.
Gravatar # re: Develop for Maintenance
by Thomas G. Mayfield at 7/10/2008 8:45 AM

I hate to sound like a zealot, but I used to have issues with undocumented build requirements--until I started using continuous integration. Something I always import into new projects is a perl script that cleans out everything not checked into subversion: http://svn.collab.net/repos/svn/trunk/contrib/client-side/svn-clean Get any of the dozens of perl-to-EXE compilers out there, and you don't have any additional requirements.

Part of the build process on the CI server (and when I set up an ultra-clean build on my machine) is to call that script. It makes for much cleaner 'svn update' calls, as there won't be unversioned files hanging around that could affect directory tree reorganization. It also guarantees that--aside from required libraries that are easily discovered--everything one needs to build the system is in source control.

I don't know of similar tools for other source control systems, but as long as there are command-line tools or libraries that can enumerate unversioned files, they wouldn't be hard to write.
Gravatar # re: Develop for Maintenance
by Robz at 7/10/2008 5:35 PM

@Thomas: You don't sound like a zealot to me.
Gravatar # re: Develop for Maintenance
by Robz at 4/23/2009 2:57 PM

@Thomas: I have to agree that everything you need for builds and deploys of a project should be in source control...
Gravatar # re: Develop for Maintenance
by Robz at 7/8/2009 3:59 PM

Automated Builds and a Build System (like Cruise Control.NET) are also a great way to independently verify the source.
Comments have been closed on this topic.