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. 
- Now, pull everything back down from source control.
- Crack open Notepad.
- Completely set up to the point you can finally run the application locally.
- 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?”
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 ... Read More
One of my colleagues in the 
