I'm current the sole developer/architect of a fairly large web application (ASP.NET MVC stack, roughly 150K+ lines of code) and the end of development is on the horizon. As such, I'm starting to think about what needs to be done for the hand off of the project and I want to make sure I do the right thing for anyone that has to maintain the project in the future.

What are some things to be aware of when getting ready to hand a project off to another developer or team of developers of maintenance?


IMHO, if you could only do one thing before handing off your project (either directly or indirectly), I would recommend that you double and tripple check that it compiles as-is from source control.

No laughing, but I cannot tell you how many times I've gotten "latest" from a source control and it failed to compile, only to find out later that I wasn't "on Fred's old box" because apparently the code "only compiles on Fred's old box". I even had a former employer promptly remove my desktop from my cube, and replace it with "Fred's old box" so I could work on the project I was suppose to.

As an extension of the above recommendation, because sometimes getting latest isn't all that is necessary to compile an application, I recommend that you create a README.txt and place it in the root directory of your application and put that in source control. This README document should contain a list of external dependencies that could not be checked into source control (if any exist), how to setup the database, and any other oddities about the compilation, execution or deployment cycles of the application.

Anything above and beyond the above two suggestions would just be gravy, but IMHO the above two are almost required on any project larger than "Hello World".


On the topic of documentation...

Over the years I've both written and read my fair share of software documentation for the purpose of easing a developer's transition. I'd say that such documents are rarely worth the paper they are printed on. Developers (myself included) rarely think of the important parts of the application while writing such documents, we only tend to think about the most recent fires we've battled. Above and beyond the fact that these documents tend to not cover all the important aspects of the software, they also get outdated VERY quickly. Once the document is out of date a future developer is more than likely going to completely disregard it instead of bringing it back up to match reality (think changing requirements).

Instead of documentation per se, I recommend unit tests. I know it probably sounds old at this point, but let the code do the documenting for you. Broken unit tests are hard to ignore (and easier to spot) than a Word document. Additionally, the English language is horribly imprecise for articulating the finner points of software design. There are simply too many ways to interpret the meaning of even the simplest of English sentences, and this just leads to confusion and/or bugs.

  • 1
    +1 for the readme file. I've actually have two of them in the project at this point, one a general "this is what I was thinking when I wrote this concept" and another that just lists all of the external dependencies and jQuery plug-ins that are in place along with lines to where I got them from. Compilation is definitely something I'm going to have to double check again though. – rjzii Nov 9 '10 at 4:12
  • @Rob, a VM is often a good idea when attempting to determine if your code can compile in a clean environment. A Clean install of Windows and Visual Studio, then run through installing only the items mentioned in your readme file. If the code compiles and runs you're all set. – Jason Whitehorn Nov 9 '10 at 4:19
  • Don't forget documentation! – Moshe Nov 9 '10 at 4:22
  • @Jason - I was able to do that awhile back under pretty much the same circumstances (two development machines, one with Parallels Desktop) but some new libraries have been pulled into the project since then. – rjzii Nov 9 '10 at 4:26
  • 1
    @Moshe - The documentation is the part that I'm actually the most worried about. I've written the code the way I would like to find it, but I'm not sure what additional documents I should be writing to supplement the code and basic readme documents. – rjzii Nov 9 '10 at 4:27

This is exactly why comments are not code smell. This is also why we should document our code.

You should make sure that you have solid documentation. There are programs that can generate documentation from comments depending on the format of the comments and the programming language.

Consider what information you would want about a library or codebase when taking it over. Ask a friend who is a programmer to give a quick look and see if they spot any obvious questions.

Good luck!


Make sure your code is compiling & packaging in the final form with just one command/click.

I can not upvote the answer What are some things to be aware of when getting ready to hand a project off? enough, so I have to write this down again.

I am very nit-picky about this one-click compilation, because I already put so much time into figuring out how to actually compile or package a project that I only had to fix one little bug. I started to put little batch/bash scripts into my projects to package the final ZIP, JAR or EAR.

In addition to that I add a README.txt to the root directory which describes the overall design, the complex parts and the project environment (in terms of communication with other departments or persons).

I try to keep this README.txt small, because nobody reads 200+ pages of specification documents if all you want to do is fix a bug, compile and package it. Implementation detail is documented in unit tests, so there is no need to write it all down again in a book...


My default handoff checklist:

  1. Check out clean copy from VCS
  2. Test build, test deploy
  3. Rename the maven repo to repo-back-up
  4. Test build again
  5. Install fresh copy of app server from zip
  6. Verify server set up notes
  7. Test deploy again
  8. Verify that no unit tests are disabled
  9. Scan comments for four letter words, delete them

If anything is broken, I'd fix it before hand over. Nothing gets someone off to a running start then getting the project checked-out, built and running the day you get the project.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.