One thing I always do before I begin updating complex code is document the flow of the code.  My rudimentary way of doing this is to start with the initial subroutine and indent each subroutine that is subsequently called, like this:

Initialize()

getProfile()

calculateRate()

updateDocs()

END OF CODE

I document my findings either on a piece of paper or in Wordpad, depending on how complex the code turns out to be.  (I'd record this in a Journal entry in Notes if the Lotusscript debugger didn't lock the Notes client--ugh!.)

If the code is particularly complex I'll use the Lotusscript debugger to figure out what's calling what.  Essentially I'm coming up with the call stack for the code for normal code execution.  I'm guessing that there must be some standard practice or way of doing this sort of documentation.  I've tried to use Visio to do this in the past, but Visio seems like a lot of overhead (not to mention cost) to do what is a fairly basic task.  Does anyone out there have a better or more elegent way to document subroutine calls?

1. Kevin Pettitt10/21/2008 09:53:44 AM
Homepage: http://www.lotusguru.com

Hey Mike, I blogged a while back about this { Link } . While I do mention a tool called Code Visual to Flowchart { Link } that might have some usefulness in these situations, you will note in the concluding paragraph that I ended up doing pretty much the same thing you did .

Via Stephan Wissel { Link } I heard about another code flowcharting tool called Visustin { Link } that might be worth checking out.

In the end, the right solution is the one that gives you what you need to understand the code, regardless of how crude the method might be.

2. John Noltensmeyer10/21/2008 09:54:22 AM
Homepage: http://twitter.com/angryjohnny

I'm really interested to see what kind of response you get on this post. In the environment I work in, we have to create a textual description of what each of our subs do for the application documentation. However, for my personal use, I end up drawing something similar to what you have pictured just because I'm a "visual" guy. However, paper doesn't scale well and I'd love to find a digital means of documenting the code I'm working on.

3. Stephan H. Wissel10/21/2008 12:39:17 PM
Homepage: http://www.wissel.net/

You also might enjoy SEQUENCE { Link } While it doesn't do the reverse engineering like Visustin it has a stunning feature. You write your call hierarchy in a kind of meta code into notepad and it generates you visual sequence diagrams: { Link }
You can use that in interactive mode or in batch (that's pretty kewl for documentation).
stw