What would you like to find when inheriting a project?

Question

I put my two weeks in to find greener pastures. Yeehaw!

Question though - What do I do with these two weeks? My users are still clamoring for new features, There are still bugs lurking around, production could be cleaner, and my bosses are politicking to figure out who, in a time of hiring freezes, is going to to maintain my project. I've done most of my code with the idea of ensuring as little headache as possible for the next guy, so my code is as clean and readable as I could do. Most of my library code is unit tested, although I don't have that much documentation out there. What should I focus on for the next guy when I'm not sure who he/she will be?

What would you, coming into a new project, find most helpful from your predecessor?

A couple of notes that are project specific:

The code base is in a proprietary language that you've never heard of, because its not used anywhere. It's like VB, and used for file to file transformations. The documentation for this language is decent, although missing anything resembling a community.

Theres no unit testing framework out there for it. I've hacked together a process to do testing, although it's not very deep. (test case works/fails) Most of my reusable code has tests, although none of my process specific code does.

There is a very good chance that my code base will move to another department, so theres a good chance that no institutional knowledge will remain. I'll be doing code reviews, but theres no guarantees that it will do any good.

We did not use version control - I kicked and screamed for it, but couldn't get any support. Versoning/development is done in folders named with a ticket number stored on a network drive

We have a wiki - I'm unsure what kind of info to put on it.

I have some home rolled tools to make things easier for me. The code is python and fairly clean - no testing or documentation for these (each tool is fairly straight forward)

The initial purpose of the project was to get off a database - there is no DB running as part of this project.

Answer 1

Documentation, lots and lots of documentation.

Explain why you made certain choices, places where you think something could be improved, and why you didn't make those improvements.

Answer 2

Based on what you have listed here I would focus primarily on documentation, with a focus on the following, in order.

1. Known bugs, if you know of a bug, even obscure, document it, and any workarounds
2. Versioning/Deployment processes, with a proprietary language and no source control, provide guidance on how you have been manging versioning and deployment, make it easy for the person to be successful.
3. Information sources/references for the language being used. Where can they go for help?
4. Document the tools, what are they at minimum and when would they be helpful. More detailed, if you have time.

That is at least where I would start, or hope that the previous person started if I was going into a position like that.

Answer 3

Documentation, starting at a high level. The next guy needs to get the big picture to know how things fit in together. Code level documentation is useless to convey this. If you have an internal wiki, this is a good place to put how everything works and the next guy will love you for it.

Answer 4

If your bosses or colleagues also care about you leaving a clean environment, explain high level architecture and key elements to them in front of a whiteboard/flipchart and get the session filmed. If there is some Q&A involved by people who are new to the project, they might ask exactly the questions that other newcomers might ask.

This way you know your audience (it's sitting in front of you) and demonstrate best will to get (in my eyes) usable documentation out for the next person.

Answer 5

Comments in the code would be nice.

Answer 6

Strong Typing. I hate it when there is a dataset and column indexers, and you have to step 4 or 5 levels into the code, then to a SP on the DB server to find out which column is which.

Answer 7

First thing is to make sure the inheritor can successfully build the software:

• Environment setup instructions
• Build instructions.
• Packaging/deployment/release instructions.

Then, I'd recommend enabling "just-in-time" learning with a collection of miniature documents:

• Top-level architecture
• Interesting interfaces
• Interesting interactions among objects/modules/subsystems

With only two weeks, you should start with the large-grained stuff, then work your way down to details. Think about it like the journalists' "Inverted Pyramid" style.

Answer 8

Hmm, to answer the question as put, it's simply

A client/boss who appreciates I am not going to grok a complex code-base in an afternoon

I have simply lost count of the number of times I have inherited a system and the client has expected me to have the intimate details of a 10k line system at my fingertips over the course of an afternoon ("you're a programmer aren't you?" and up and productive coding of all the things the departing developer never quite finished within a couple of days.

So sure document, but a quiet word with the boss that you'd expect you're successor to take x weeks to get up to speed would sure be appreciated.

Answer 9

I would like for all my work to already be done.

Barring that, a set of nice tests and a nicely setup development and production environment would be great.

Answer 10

I'd like to know the general flow of how things work to complement the codebase. This would include the following where applicable:

1) Feature requests -> Where are these stored, how are priorities set, how often do they change, etc.

2) Bug-tracking tool -> Is it just stored in e-mails and spreadsheets or is there a package used like Fogbugz or Gemini Bug Tracking.

3) Version control -> Where is it and how are things arranged.

4) Software Development Methodology -> Is it waterfall, agile, XP, Scrum, or some hybrid of all of the above?

5) Testing -> Is there a QA team or someone that will test the code or does it just go into production and if users find bugs then I fix them, which really isn't a good idea most of the time.

6) Standard and practices document -> This is likely something you could write to state what kinds of conventions and standards did you use in the code like how you named variables, methods, tests, and class names.

I think those would be my main things that would help me a lot.

Answer 11

Here's what I would like to see. Some of it is mentioned in other answers already.

• High level documention. How do the different big parts work together?
• Prioritized list of what to do next. What would you be working on if you were sticking around?
• List of trouble spots. What has been full of bugs? What is likely to bite me that I don't expect? Are there users I should watch out for?
• Instructions on how to get started. Complete enlistment and build directions if there's anything complicated.

Answer 12

In addition to the great comments by Mitchell and mtnygard:

List of Gotchas

Good development follows the principle of least surprise. But grubby reality intrudes and there are always surprises in store in any code base. Single these out, describe them, describe the rationale for why they are the way they are. Good examples are processes that require a lot of manual assistance, dead/deprecated code, unused code that was written to fulfill some speculative need that didn't pan out, and key design weaknesses.

Documentation of Intent

Amidst all the what and how, which are obvious necessities, you need to clearly document the why. Why does this or that tool exist? Why was it built this way instead of another way? Why is X part of your process? Why isn't Y (e.g. source control) part of your process? Etc. If you leave out this critical information then people will start to assume that the intent of the system is merely to be exactly as the system is currently. This will lead to people leaving hacks in place because they think they are by design rather than merely flawed execution reaching for a different goal, for example.

Roadmap for the Future

Spend some time describing at a high level where you think this project should go. It's unlikely that the inheritors will follow or be able to follow that roadmap exactly but that information helps a great deal in giving context and guidance to the new owners.