Documenting/Flowcharting in VB5

I am having some difficulty documenting program flow for both myself and for program users.

In DOS programming, where everything is linear, it was always easy to document programs with flowcharts. All the branching could be easily diagrammed with If..Then..Else, Select Case...End Select and Do...Loop flowchart symbols.

In Object Oriented programming like VB, everything is triggered by "events" such as Click and Double Click. This makes it extremely difficult to write up a meaningful description of program flow in pictorial form.

I would like to be able to do this for two reasons:

1 - Documentation for program users to help explain how the program works.

2 - Documentation for myself, so that when I come back to the program for modifications (sometimes several years later) I will have some idea how it works and what triggers what, without having to review every bit of code and every possible event.

Does anyone know of any good on-line information re documentation methods for VB programs or of any good books which would help?

Conventional flowcharts are ok within events but are impossible for showing the relationship between events.

You really need to fall back on state diagrams to understand the structure of an event driven software module. Core state is *IDLE* - your code is *NOT* running! Idle is exited by "Keyclick" or "Mouse" events. Also can be exited by "External Shutdown" or possibly some other event state that you've been waiting for. Each Form has it's OWN IDLE. When several forms are on screen it can be *hairy* to show - clearly - the "correct" event relationships.

I expressed a form event series as an indented list:

Form.Load
Form.Activate
...
Form.Deactivate
Form.Unload

This shows the sequential nature of the events that fire, but tells you nothing about what it did.

I would suggest a checklist for each form. List all of the events that can occur on that form and highlight the events that have an external effect. That is, if an event is handled entirely internal to the form, it's a local change. But events that have, say, a Me.Hide in them effectively transfer control back up the food chain - if you're MODAL! (sigh). Other events might spawn child events leading to OTHER forms like FormX.Show.

I don't know a clear way to express this. Visio might be one approach, AutoCAD another, neither will generate a clear structural diagram automatically.

I spent years working in DOS versions of Basic (Microsoft VB7 Professional Edition) and rigorously followed the strict rules of structured programming to eliminate spaghetti code and eliminating "GOTO" statements which permit multiple branches in and out of various parts of the program.

Now on switching to VB, I find that the various "events" can be triggered by clicking or by form load/unload/activate/deactivate/lostfocus etc. and even by directly calling events up by code in another section of the program. This creates such a complex interleaving of branches and jumping around in program code that it makes the WORST DOS programming flow chart look positively clean!

I like your idea of a checklist for each form and documenting the internal and external events for each form. I try to document with REM (') statements at the beginning of the code for each event.

Just a comment on your indented list (see below):

Form.Load
Form.Activate
...
Form.Deactivate
Form.Unload

I have found (using debug.print statements) that even this is not as simple or as intuitive as you might think. Sometimes VB puts its activate/deactivate/gotfocus/lostfocus (etc.) events in a different order than you would expect. You would think that all the events from a form being unloaded would be terminated cleanly before the events in the next form would start to fire, but this is not always the case. I wish this were better documented!

Have you seen state diagrams? Each state is a circle with a curved arrow connecting to other states. Each arrow is labelled with the event that triggered the state change. Can't show one here in a text only environment.

State diagrams are probably appropiate, however, things become complicated if events are combined (like a click during which a timer occurs).

For real-time programming (in DOS, using interrupt handlers [yes, it's possible]), I used the following technique: the program usually ran in an endless loop (state 0). Whenever something happended, a state variable was set to a value depending on "something" (i.e., they actual event) and returned to the main loop. In the loop, I checked for the current value (combination) in a big CASE statement. I had then all the logic in one place and all triggers in another place; it's quite easy to comment, too.

Quip doubles as a “living” wiki and a project management tool that evolves with your organization. As you finish projects in Quip, the work remains, easily accessible to all team members, new and old.
- Increase transparency
- Onboard new hires faster
- Access from mobile/offline

Yeah, you reallly have to have a background in writing interrupt based code to get a grip on the non-linear nature of VB. My years of writing realtime .ASM code has made the transition to VB easier, but the first couple of programs I wrote still took me up a fairly steep learning curve.

Problem I have with state diagrams (and state driven code for that matter) is that you can't stand back and *see* the structure of the code like you can with linear flowcharting. The state relationships don't give you a clue if a state is happening every clock tick or once every alternate leap year.

Tip: Each state circle should list Global values that it modifies. Ditto calling and returned values. This helps show encapsulation.

Unfortunately it is a concept I am unfamiliar with. Does anyone know of an internet resource or a good book which covers the basics?

Anything I have read so far seem to support mark2150's comments that State Diagrams don't provide an intuitively clear picture of program structure. Most articles seem to indicate that State Diagrams become extremely complex with large programs.

I've been doing multi-tier client server development with VB for some time. State diagrams are of limited use, IMHO, for documenting GUI applications. All of my analysis and design for applications over the last couple of years has been done using the UML (Unified Modeling Language), which is a standard OO notation for capturing requirements, analysis and design. UML contains state diagrams as a possible deliverable, but I've found that state diagrams in *business software* (don't know if that's what you're doing) tend to be used as documentation for business-oriented concepts (such as the state of a loan application) as opposed to detailed event-handling in forms.

If I were you, I'd look into using dynamic class models to document the events that are *most interesting* in your program. For example, if you have a button 'b' on form 'f', that has very interesting or complicated behavior, you'd document the b_clicked---->f event in your dynamic model (which uses boxes and lines to show the flow of control from object to object), which would allow you to show what other things happen as a result of the click. With a good design, generally those other activities are delegated to other objects in your system (you don't code everything into your form).

There are plenty of sources on the UML in the bookstores now. Be prepared -- UML is a deeply OO technique for documenting and designing systems. If you aren't already an OO "heavy" be ready to learn a lot. You may find that it's difficult to document your existing systems using UML if you didn't take an OO approach in the first place, or if you didn't decompose your event handlers effectively. I'm not trying to scare you, just to warn you of the learning curve :-).

If you aren't worried about the learning curve, be prepared to have a lot of fun designing systems using OO techniques. It takes a while, but once you learn how to apply the techniques you'll wonder how you programmed the old way. You know you're there when you "think in objects", rather than thinking functionally.

Be warned -- none of these books focuses on VB as the development tool. UML doesn't have anything to do with how you implement the designs in a given tool. You'll have to do that mapping yourself (or ask questions here, which I'll be happy to answer, if I can).

Now for your user documentation, UML deliverables just aren't going to cut it. In my experience, creating user documentation takes talent, desire, and good writing skills. You are not the best person to write it (necessarily), because you are so intimate with the functionality of your program. It's better for a pro writer to do it. But, when does that ever happen? :-) If you're going to do the user doc, I'd take the approach of screen printing the windows of your app and using a paint package to call out specific buttons or controls, and explain how they are used. This is a topic for a whole other question, so I'll stop there. :-)

Visit my site at http://www.digitalanswers.com, where I have more detailed reviews of the above books. There's also a paper there that shows what one type of UML model looks like (unfortunately, not a dynamic model, but a static one).

Thanks for taking the time to give me very competent and comprehensive answers to my questions. From what you say I guess I need to decide how much time to commit to learning these new techniques.

Software development is a nasty business sometimes! Just when you get really good at it, somebody comes along with a new development language which sends you back to square one again (do not pass GO, do not collect $200 etc.)!

I was getting really good at writing and documenting structured DOS BASIC programs and along comes OO (Visual Basic). Am I getting too old for this? Oh well, enough philosophical musings for now! Back to pondering simpler questions like the meaning of life!

Featured Post

Quip doubles as a “living” wiki and a project management tool that evolves with your organization. As you finish projects in Quip, the work remains, easily accessible to all team members, new and old.
- Increase transparency
- Onboard new hires faster
- Access from mobile/offline

Enums (shorthand for ‘enumerations’) are not often used by programmers but they can be quite valuable when they are.
What are they?
An Enum is just a type of variable like a string or an Integer, but in this case one that you create that contains…

Background
What I'm presenting in this article is the result of 2 conditions in my work area:
We have a SQL Server production environment but no development or test environment; andWe have an MS Access front end using tables in SQL Server but we a…

As developers, we are not limited to the functions provided by the VBA language. In addition, we can call the functions that are part of the Windows operating system. These functions are part of the Windows API (Application Programming Interface). U…

This lesson covers basic error handling code in Microsoft Excel using VBA. This is the first lesson in a 3-part series that uses code to loop through an Excel spreadsheet in VBA and then fix errors, taking advantage of error handling code.
This l…