Methodology for Documenting Existing Code Base

Question

I work as part of a team on an existing application that has no inline documentation, nor does it have technical documentation. As I've been working on various bug reports on the application, I've written a sort of breadcrumb trail for myself - bug numbers in various places so that the next developer can refer to that bug number to see what was going on. My question is thus:

What is the most effecient method for documenting this code? Should I document as I touch the area (the virus method, if you will), or should I document from each section on its own, and not follow paths that branch out into other areas of the application? Should I insert inline comments where none previously existed (with the fear that I may end up incorrectly identifying what the code does)?

What method would you use to accurately and quickly document a rather large application that has no existing inline documentation, nor inline references to external documentation?

Answer 1

I would document as I added/modified code. Other than that I would also document public APIs or any interfaces between modules. If you were to document all of the code you may not see the ROI for the time spent. It may be useful to use something like a wiki to organize external documentation as you develop it. The most useful document I referenced when I started on my last project was the architecture doc. It included information about technologies used and it provided a high level view of how the application was layered.

Answer 2

Tricky question. Basically, I'd use the "refactoring" method, which I would restate as "if you touch the code, document it".

But to be precise; as issues come up, and as you have to gain familiarity with the code to fix the bugs that occur, I'd say you should use that familiarity to write comments on that code in particular; in essence, the motivation to fix the bug has at that point forced you to gain enough familiarity with the code to be able to document it. And for that reason, I'd be leery of following unrelated branches OR of documenting unrelated functions, because at that point, if you're not performing active testing of the code (to verify your bug fix), then it's hard to be totally certain that you understand precisely what the code does and why. (I'm not getting into the issue that it can also be hard to figure out precisely what and why the code does what it does even when testing a bug fix; you've probably figured that out from your experiences.)

This approach should tend to maximize accuracy, with a sacrifice of overall speed, but not impact your need to maintain the code too severely at the same time. If your bugfixing duties are small, of course, you can venture into "unknown territory" and begin documenting there, but if you (like most of us) can't find enough time in the day to both fix code and document it, this is a good compromise.

One thing bears noting as well; you should have good external documentation. You say that your code doesn't have references to external documentation; I hope for your sake that such external documentation exists, though. If not, I'd actually make writing that external documentation your first priority; something on the level of a functional spec is, I think, absolutely critical to all big software projects. The reason is that functional specs, or high-level documentation of that form, can help prevent "feature creep" or "feature drift" in any software; and feature drift (in particular) can be destructive to documentation as it can cause the documentation to become out-of-date. (I define feature creep as the progressive (and annoying) addition of features to a piece of software; feature drift, on the other hand, is where the set of actions that software takes slowly changes over time. Feature creep is ADDITIVE, i.e. it usually involves increasing the set of functionality of the software; feature drift, on the other hand, is zero-sum; one by one, one piece of edge functionality gets defined to do something different, until the software is doing something completely different than originally intended. Feature drift is rare, but DEADLY for documentation.)

Answer 3

Before you start documenting anything, develop a standard. This can be as simple as making sure you write a few lines above a function or class header to something more official and verbose (like javadoc). Before anyone can check in code, their documentation must meet that standard.

What I've found works well is adding well written comments before the function header to functions I've created that were previously undocumented, and adding inline comments to anything that I've added. You want to avoid documenting code that you haven't touched. It's worse to have bad comments than no comments, and if you're documenting this 'quickly', you'll probably write bad comments.

Answer 4

One application that I co-developed over the course of two years had a serious lack of documentation. At some point it became clear that we going to pass off the application to another developer who was going to maintain it from that point forward, so we had to document the code.

In order to deal with the gigantic scope of the documentation process, I would try and document all of the code in a specific feature or part of the app on a given day. I had no particular pattern, but an insistence on doing some each day, and getting a sense of completion by documenting a whole file or section of the app daily.

It took months to document the entire application, but at a half-hour(max) a day it never really ate into the project schedule and avoided a lot of the tedium that goes along with documenting.

We used the XML documentation in C#, and it provided enough features and structures to make documenting easy. Even if your not documenting a C# app, the pattern of having a short summary first followed by remarks was very usfeul.