documenting existing code

Question

I just joined a Heroic shop. The code appears to be clean and quality, but there is no documentation to speak of. (the code was written and maintained by a small group). Thus, new engineers need to reengineer from source to determine design. As the project is transitioning from a small (3) team to a larger team, I would like to document my efforts to learn the applications so the next hire can learn them more quickly.

A quick search of "document existing" + application | code doesn't yield much. I am sure this is a common question, so reference to another discussion might be the best.

Any suggestions?

Answer 1

What language? Depending on the language, something like doxygen could be very helpful.

Answer 2

Another easy starting point is a wiki. Documenting or diagramming the high-level structure of the system/application so everyone has a decent starting point should be a priority, and a wiki is a convenient way to get the info out there. (I'd be surprised if there was no documentation at this level from the original 3, but I bet they could whomp up something useful very quickly...)

Answer 3

VSdocman (http://www.helixoft.com) is excellent tool for generate documentation for C# and VB.NET. They also has tool for VB6. You can download 14 day trial version. Price started from $229 for .NET version and $79 for VB6.

Answer 4

Consider doing some of your documentation in the form of automated tests. Then you'll (a) verify that the code really does work the way you understand it to, and (b) build up a suite of regression tests to let you know if you break something later (e.g. due to not realizing that changing X will cause a side effect in Y -- very possible even in code you are familiar with).

If you don't know how to get started with adding tests to existing code, pick up Michael Feathers' excellent book "Working Effectively with Legacy Code".

As for (easily) human-readable and -skimmable documentation, Fit and FitNesse can produce human-readable, but executable, tests, especially when the requirements can be represented in a grid (these inputs -> these outputs).

Answer 5

Backing up what Jeff K. said, I'd go with a Wiki, with privs spread as wide as possible (ideally to your users too). Once people know it is up, putting up a stub for each program will often be enough to catalyze several iterations of updates, culminating in rather complete documentation suprisingly quickly. Engineers may hate documenting things, but we can't resist fixing something we see wrong.

Worst case, you end up revision-controlled documents which nobody but you ever edits. That's no worse than you have now.

Answer 6

Depending on how complex the code is, I've done a few things.

You probably want to go over each method/fucntion/object/whatever (you didn't mention a language) and try to understand what it is doing. If you have ANYTHING that takes you more than a minute to understand, figure out what you didn't understand and write a comment so the next time it won't take you that minute.

Understanding how all the parts relate to each other can be tough unless the design is very well done. Printing debug output at the entry/exit of each routine and using stack dumps can be helpful to see how you got some place. A debugger can be awesome for figuring this stuff out.

A final tool I found to be really useful is a profiler. I had a free profiler plug-in for Eclipse (I forget the name, but I don't think there are many) that would create an awesome sequence diagram for any code it went through as it was running. This may be the best tool I ever saw for understanding what the code was doing. It was a bit difficult to set up at the time, but keep at it, it's doable and well worth it.

I turned on the profiler, hit one button/executed one task, then saved the "Run" for that button.

I filtered out classes that were trivial and got it to a semi-reasonable size (Some were 2 pages, one sequence diagram took 4x6 sheets of paper to print (landscape)). I taped them all together and put them on my cube wall and studied/documented the hell out of that thing.

Sequence diagrams rock when done right, by the way. If you are trying to understand some code and you don't use sequence diagrams, look into them. I think they are probably the most useful design documentation tool I've seen.

Answer 7

If there are few or insufficient comments in the code, Doxygen will have limited value. However, it can still be used to give you some idea of the code structure and dependencies. (Things like a profiler are great for understanding the behavior.) I find pictures helpful for understanding dependencies and usually run the code through a UML tool to reverse engineer the design. You can get similar, class diagrams by using Graphviz, which can be integrated with Doxygen pretty easily (even for non-object oriented code).