dougr
asked on
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?
dougr
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?
dougr
ASKER
To: mark2150
Thank you for your comments on my documentation question.
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/deact
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/gotfoc
dougr
Thank you for your comments on my documentation question.
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/deact
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/gotfoc
dougr
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.
M
M
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.
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.
The state diagrams (bubbles and string) are the perfect answer for this, I use them all the time. I am an electronic engineer and use them for electronic design also.
I just draw them in MicroGraphix FlowCharter.
I find they translate directly into case statements, so my programs usually have a huge state machine routine in the center. eg
select case state
case idle
select case event
etc...
Designing the code in this way means you can guarantee coverage of the requirement spec and makes it easy to ensure all events in all states are tested.
There is no problem where events occur together in windows, in the example in the previous comment you must have both events on both states then you can eliminate race conditions.
Still i'd love a program that code reverse engineer them for me!
I just draw them in MicroGraphix FlowCharter.
I find they translate directly into case statements, so my programs usually have a huge state machine routine in the center. eg
select case state
case idle
select case event
etc...
Designing the code in this way means you can guarantee coverage of the requirement spec and makes it easy to ensure all events in all states are tested.
There is no problem where events occur together in windows, in the example in the previous comment you must have both events on both states then you can eliminate race conditions.
Still i'd love a program that code reverse engineer them for me!
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.
M
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.
M
ASKER
Thanks to all the responders for your comments re State Diagrams.
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.
dougr
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.
dougr
ASKER CERTIFIED SOLUTION
membership
This solution is only available to members.
To access this solution, you must be a member of Experts Exchange.
ASKER
TO: mithomas
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!
Thanks again Mike for your good response. I will visit your web site.
dougr
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!
Thanks again Mike for your good response. I will visit your web site.
dougr
Thanks for the points! If you have any further UML/VB questions post them in the General VB area (I've asked EE to add OO as a topic -- hopefully they will at some point).
Good luck...
Good luck...
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.
M