How to write Reverse Code Engineering Documents?

[3pmilk]

Hi all,

My boss has given me a new assignment today. She wants me document an existing application that I have no clue on. Apparently, the developer who created this VB application is leaving and is not going to provide any documentation for our department, so it’s my job to interview, gather info and document. I’m supposed to write this document as if I’m writing for another developer. If you can provide me any examples or websites on how this document is supposed to be written, the level of details that it should include, I will appreciate it greatly!!!

Thanks,
Wendy

 

[chiph]

I don't think there's an official format for this.

I would just start with a summary of what the program is supposed to do, then do a high level summary of features, then drill down in progressively more detail.

How much detail is up to you -- you'll probably be the one tasked to maintain this code, so get as much detail as you need to do this.

Chip H.


____________________________________________________________________
If you want to get the best response to a question, please read FAQ222-2244 first

 

[3pmilk]

Thanks for the tip, Chip. What you say makes sense, but I just wish there's some sort of sample documents on the web to give me an idea on how to start this document.

 

[BobRodes]

You might find it helpful to think of the problem that you have to solve in terms of "what does the program do?" and "How does the program do it?" Organize the answers to these questions separately.

If you're looking for a formalized system for defining applications, try looking into the RUP (in particular, the inception and elaboration phases) and UML (use case and possibly class diagrams).

You'll need a "problem statement" even though the "problem" has been presumably solved by the existence of the application. A new app will have this statement, which defines the "problem domain." This domain is the set of business issues that the application seeks to address, and a general overview of how it will do so.

Another "artifact" or "deliverable" is the "semantic dictionary." This is, as its name suggests, a dictionary of words as they are used in the problem domain, and should include all of the business terms in the domain.

Look into UML Use Case diagrams for a means of diagramming the behavior of the domain, and class diagrams as a means of defining the structure of the solution.

For an overview of the RUP check

http://en.wikipedia.org/wiki/Rational_Unified_Process

For all things OO, including UML, you'll find hundreds of links on

http://www.cetus-links.org

HTH

Bob

 

[chiph]

Good ideas, Bob.

It'll probably be very useful to create some sequence diagrams. Since it's VB6, I don't think class/entity diagrams would be that useful (the language isn't 100% O-O)

The dictionary is a good idea to, so that the problem domain is defined in common terms. Perhaps setting up a Wiki could be useful. Certainly a lot more flexible than a MS-Word doc.

Chip H.


____________________________________________________________________
If you want to get the best response to a question, please read FAQ222-2244 first

 

[BobRodes]

<Since it's VB6, I don't think class/entity diagrams would be that useful (the language isn't 100% O-O)

This is one of those rare instances where I don't agree with you, Chip. I've found them to be useful in my experience. The fact that VB isn't 100% OO doesn't mean that VB application structure can't be usefully represented by UML class diagrams. Just use the parts that ARE supported by VB, such as aggregation, composition, association, multiplicity, attributes, methods, interfaces. (In other words, don't use inheritance or abstract classes, but all the rest is useful.)

I do agree with you on Sequence Diagrams, however. 3pmilk, sequence diagrams detail how instances of classes interact over time. (Sometimes Collaboration diagrams provide the same material with a different emphasis; often modelers use both.) If you put together a class diagram first (so you can be clear on what interacts with what), you can begin to detail that interaction using sequence diagrams.

Think of class diagrams as structural, and sequence diagrams as behavioral.

Bob

 

[chiph]

My concern is that many VB programmers use global variables located in .bas modules, rather than real classes in .cls files. Those are probably OK to model in Analysis, but more difficult in Design, as there's no "instance" to them (it's all just one instance).

But, as you say, they may still prove useful in showing what talks to what.

Chip H.


____________________________________________________________________
If you want to get the best response to a question, please read FAQ222-2244 first

 

[BobRodes]

<more difficult in Design, as there's no "instance" to them (it's all just one instance).

Well, the common way to model .bas modules in UML is as a class with the <<utility>> stereotype on it. (This is also the case with classes whose Instancing property is set to GlobalSingleUse or GlobalMultiUse.) The utility stereotype simply defines the class as a non-instantiated set of global attributes and/or methods. This is actually quite common usage, and I don't see why it's difficult.

Now, while I take your point that a lot of VB programmers don't use class modules (I got a bit of a late start, so I do all the time, and tend to forget that there's a lot of code out there that doesn't), they still use forms and forms are classes. So, the basic idea of encapsulated entities in intercommunication, which is the cornerstone of class structure, is there in a VB app.

In my personal experience, I have indeed found class diagrams useful in determining what talks to what, and how, and also what "what" is.

Bob

 

[chiph]

the common way to model .bas modules in UML is as a class with the <<utility>> stereotype on it

I haven't seen that. But it makes sense!

In my personal experience, I have indeed found class diagrams useful in determining what talks to what, and how, and also what "what" is.

If we haven't lost 3pmilk, hopefully this will be of use to them.

3pmilk -
Good & relatively cheap (ie. not thousands of dollars) tools for diagramming UML include:
Enterprise Architect (

http://sparxsystems.com/)

and
Magicdraw (

http://www.magicdraw.com/)

Be aware that there is enough functionality in these tools to overload you. I would also recommend a couple of UML books, such as UML Distilled by Martin Fowler.

Chip H.


____________________________________________________________________
If you want to get the best response to a question, please read FAQ222-2244 first

 

[BobRodes]

Also, Visio has a reverse engineering tool for VB6 projects into UML. I've used MagicDraw and it's a good tool too.

A great book on UML, very comprehensive, is the UML Bible by Tom Pender, from Wiley Press. (I helped to edit it, so take my recommendation with a grain of salt, but the reviews are great too.) I've seen copies of Fowler's book thumbed into tatters, too. Another great book.

Bob