How to pass on a large codebase?

Question

I am a university student and I have been working on the same software project for the past two years. It is not a class project; it is sponsored by an outside organization, and it has been my part time job during the school year and my full time job during the summer.

I have to complete everything by the end of the summer, and the functionality of the software will most likely get done, but I am concerned about handing it off to the next group of students who will maintain the code. A professor has been advising me, but I have been mostly working on this thing alone, so no one else really knows how the system works. It is up to around 8000 lines of code by this point, and I'd like your input on the best ways to document this project. My advisor says that every part of the system needs to be documented in one way or another, but I don't want to go overboard on comments. How can I best make it understandable to new programmers?

Answer 1

• Code should be written clearly, so it's easy to see what it's doing. Well-written code often suffices as its own commentary for the mechanics of how things get done - especially if variable names and functions are descriptive.

• Comments should be written in such a manner to explain why it's doing whatever it is. If you had to actually think about a portion of code for longer than 5 minutes before writing it, it's probably good to add a comment explaining why things are being done the way they are.

Probably the most useful non-inline documentation you can prepare for those coming after you is a general overview of the system - what components do what, and how they interact. This allows someone new to have a good lead on where they should start digging if they need more specific information.

This general overview can also include a summary of the major design decisions involved - basically, a high-level version of the "why". Knowing this can help a lot when trying to extend a system, because "going with the flow" design-wise often simplifies interaction between old and new code greatly.

Answer 2

Personally I find comment inside the code itself the most important to find. Comment about a method and its parameters is nice to have but what's going on inside a method is the most important. Others might find bugs and at such moments someone else needs to be able what those couple of lines of code do.

Grz, Kris.

Answer 3

The problems with individual function point documents (typical with things like JavaDoc) is while they document the functions, they don't document that System. This is much like the difference between a "Users Guide" and "Reference Guide".

Assuming you can not do both (both are ideal, obviously), a User Guide to the system is much more useful. Something the shows the systems entry points, ideally how they progress through the system. Good examples are things like UML Activity Diagrams, which show how the different components interact with each other.

The reason this is more important than functional documentation is that, truth be told, if the code isn't super complicated, functions are, for the most part, "self documenting". They have the code, they can read the functions.

But how they go together is not necessarily as clear, particularly if you have any high level abstractions (lots of interfaces, factory patterns for actual implementations, etc.)

So, higher level, task based workflows I think work best. If you have any particularly hairy code, then, certainly, document those specific points to help clarify what the code says.

But on a transition team, where folks mostly want to know where to go to add feature A or fix bug B, the activity flows I think give the best direction.

Answer 4

For me the most important part is to have a overview of a project. I mean some kind of diagram that will show the role of every part of the program and the interactions between those parts. Then, if the parts are still big, you may add other diagrams describing them. (Those diagrams should be also commented, because not everyone likes images.)

I think that you should document more the interfaces than implementations as they describe the purpose of the parts of your system.

Answer 5

I've seen too many people who think that documentation is about listing the inputs & outputs for each function, but if someone's going to be taking over a large project like this, you'll want to describe what the known requirements are for the project, the overall design, what sort of external components it deals with, etc.

You don't want to get into the situation where someone wonders why something's been written the way it is, and decides to rewrite it to 'simplify' it, and ends up removing some sort of critical business logic, so make sure to document why things are written the way they are.

Documentation, like anything else, needs testing -- just because you understand the language you're writing the documentation in, doesn't mean it'll be easily understood by the people who might need it. Try to keep the language accessible -- programming jargon is usually okay, but be careful of local jargon that a new person might not understand. If you can, get someone to read it over to make sure it seems to make sense -- of course, as they're not going to be the ones needing the documentation (as from your description, you'll have no overlap), it won't be a complete test.

For what you're asking for, you have no idea what the next maintainer's background is -- if they're at least likely to have taken a number of courses at the school (ie, undergrad senior, not starting grad student), you might be able to assume that they're at least familiar with the required courses in your program. ... if it's going to be maintained by the external company, all bets are off.

Answer 6

From the Architect's Perspective

I had a similar experience over the past year, providing support for several newbie devs who were maintaining an application I wrote.

Your main objective is to teach them how to be productive while working with your code.

Don't underestimate how useful it will be to walk them through* the process of setting up their development environment, establishing workflows (bug tracker, source control), etc. If you spell this out in step-by-step fashion you can almost guarantee they'll do it, and it'll make everything easier.

Likely, new devs are going to start small and tweak features or fix bugs. So keep it simple and write some use cases. I.e.

• "You want to add new feature X, this is how you do it."
• "You are asked to change the way old feature Y works, this is where to look."
• "I planned to add new feature Z, these are the functions and/or classes you'll need to use, and it should be attached to ..."

In hindsight, I'd definitely provide some diagrams about how the software works, from a big picture perspective. Full UML might be a bit overkill (presuming anyone knows how to read it anyway), but I think a few simple flow diagrams should suffice.

*By "walk through" I mean "write an explanation". If it's written down, no one can forget it. Also, if you have time, make yourself (reasonably) available for questions. It helps. ;)

From the Maintainer's Perspective

I'm currently maintaining a huge amount of undocumented (and poorly-designed) code, and even though I have a good idea of the top-level stuff, there are a lot of implementation details that are very frustrating.

Things you should avoid (or clearly document if you can't undo them):

• Vague variable names
• Global variables (what changed it?)
• Over-purposed functions (one function does everything!)
• Non-obvious flow or control structures (nested conditional includes inside giant conditional code blocks, for instance)

If you know there are a few things you kludged together to meet a deadline or work around a bug, be sure to provide some well-composed prose that explains how it works, if you can't just refactor it entirely.