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 efficient 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

Documenting legacy code-bases

I would highly recommend following the scout rule with legacy code-bases.

Trying to document a legacy project independently of working on it will just never happen. Even if you get in contractors to do it, as soon as they finish the project, that documentation will start falling behind all over again, because developers haven't got into the habit of updating it.

In-code documentation

The most important thing is to use the documentation facilities in your chosen development environment, so that means pydoc for python, javadoc in java or xml comments in C#. These make it easy to write the documentation at the same time as writing the code.

If you rely on coming back and documenting things later, you may not get around to it, but if you do it as you are writing the code, what needs to be documented will be fresh in your mind. C# even has the option to issue a compilation warning if the XML documentation is incomplete or inconsistent with the actual code.

Also, if reviewing documentation becomes part of your code review process, everyone can be encouraged to contribute, fostering a sense of ownership of the documentation as well as of the code.

Tests as documentation

Another important aspect is having good integration and unit tests.

Often documentation concentrates on what classes and methods do in isolation, skipping over how they are used together to solve your problem. Tests often put these into context by showing how they interact with each other.

Similarly, unit-tests often point out external dependencies explicitly through which things need to be Mocked out.

I also find that using Test-driven development I write software which is easier to use, because I'm using it right from the word go. With a good testing framework, making code easier to test and making it easy to use are often the same thing.

Higher level documentation

Finally there is what to do about system level and architectural documentation.

Many would advocate writing such documentation in a wiki or using Word or other word processor, but for me the best place for such documentation is also alongside the code, in a plain text format that is version control system friendly.

Just like with in-code documentation, if you store your higher level documentation in your code repository then you are more likely to keep it up to date. You also get the benefit that when you pull out version X.Y of the code, you also get version X.Y of the documentation. In addition, if you use a VCS friendly format, then it means that it is easy to branch, diff and merge, just like your code.

Not only that, but if you use something like readthedocs then you can publish version specific documentation for each software release.

I quite like rst, as it is easy to produce both html pages and pdf documents from it, and is much friendlier than LaTeX, yet can still include LaTeX math expressions when you need them.

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

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.

Answer 4

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 5

I would use Doxygen comments. Doxygen has more output formats that most other free formats and is simple to learn.

You might even consider hiring a contractor to do this, as some of us do it for a living. However, with this choice you still have to commit to reviewing the docs.

Another common technique is to assign the new dev to documenting the code. Then have each new person go through it as they get up to speed. Be aware that some devs look at this as getting a root canal--necessary in only the direct cases, LOL.

Answer 6

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.