I'm asked to analyze the program responsible for printing our invoices. (Via SAP script)

This program is pretty old and contains more than 4.000 lines of code. It sets a lot of different variables under a lot of different conditions. Luckily the coding itself is not very difficult (A lot of if / else, cases, and loops) and I think I could write some sort of "compiler" to translate the coding into something understandable by the people who asked me to do this.

Basically I'd like to write a documentations / program / excel sheet / whatever which is able to answer questions like "Under what conditions will the printed price field include VAT?" / "Which database table fills the address field?"

I need to visualize what parts of the coding influence a given variable. Currently I think some kind of "inverse tree" starting at the variable itself and going up through all "IF"s "LOOP"s etc. might get the job done.

Do you think this is a good idea or do you have another suggestion to visualize this?

To clarify my problem a bit more, as @Jeroen suggested:

  • I need to create something which spans the complete program. I.e. my users should be able to understand whatever part of the program they are interested in without asking someone else or learning how to read ABAP code.
  • My biggest problem right now is Visualizing a LOT of different variables and programm flows in a easy-to-understand and easy-to-navigate way.
  • 1
    Does it need to be a visualization? Unit- and/or integration tests could help too, and they'd remain useful if business will follow up by asking for changes. They'd also allow you to be reasonably certain you're correct. The business could be presented with just the descriptions/titles first, diving into details when asked... – Jeroen Jan 16 '15 at 9:45
  • 1
    @Jeroen No, it does not. The requirement boild down to "leave some kind of documentation which allows us to answer the above questions on our own" as my internship ends in February. But this documentation will aid the department to formulate the tests for futher work on the program. (I know it's usually "requirements first" but due to how the program developed over the years and employes came and left there is not much left beside the source code) – Dennis Jan 16 '15 at 10:03
  • Is it absolutely necessary for non-programmers to see the source codes? Or can the code be represented in process flows? – Ades Jan 19 '15 at 10:03
  • In the early days of flash programming the UI tried to let non-technical people write code logic using buttons and drop downs - I thought it was a horrible experience but maybe that's because I was already used to writing code. I really like this question and hope I can find some time to give it the thought it deserves. – DaveAlger Jan 19 '15 at 17:52
  • 1
    @Dennis if that's the case, then it's still possible to visualize it via the user flows/process flows. You just need to break the flows into separate journeys (e.g; login, registration, forgot password, purchase..etc) and then come up with different flows for each. – Ades Jan 20 '15 at 10:13
up vote 32 down vote accepted
+100

The easiest way to accomplish this is with a flow chart diagram using MS Visio or something to that effect.

That could look something like what Visustin - Export to Visio has on their page:




Edits based on comments:

As @Sharky said in the comments, "You may want to add pseudocode, also."

Which, if you don't know, means English for execs that may only understand high-level terms.

That looks something like this that Alex in his article The App Inventor created :


You can also do a mix of the two. If you are going to try and diagram all of your code, it could wind up quite large depending on the size of your project; it just depends on how granular you want to get really.

You have to think, am I going to do the only the presentation / UI layer, or do I include the business logic layer too, and finally what about the service / data layer? When you add all that up, it could be massive depending on your project. That said, since you said it's only about 4k lines, mixing up the pseudocode and actual code might not be a bad idea.

Or ...

If you've documented your code, there might be plugins / add-ins / software out there (I'm sure there is) that will automatically create a help / documentation guide. Then, you could mix in some pseudocode Visio diagrams as visual representations of your comments. You would just need to look around and see what you can find. Might be free, cost a little, or cost a lot.

In my opinion though, it'd be worth it, as it would cover all your bases and probably be the best option, as it would mix everything together and would be suitable for anyone who reads it whether it's a programmer or a high-level exec or anyone in between.

  • 1
    you may want to add pseudocode, also – Sharky Jan 19 '15 at 10:43
  • @Sharky - Yea, you definitely would want to for those who are a little more high-level, like execs. – Code Maverick Jan 19 '15 at 10:48
  • @Sharky - Added a pseudocode example for ya. =D – Code Maverick Jan 19 '15 at 11:59
  • 2
    No need for me to answer, whan you already have made the one I was thinking of. Good answer, Maverick! – 4rchit3ct Jan 20 '15 at 8:39
  • I really like this answer and will probably do something very similar. Still not sure if I can display the entire program this way - but compressing unneccesary parts to pseudocode might help with this problem. I'll wait a few more days in case someone else has another great idea and will select yours otherwise. Thanks! – Dennis Jan 20 '15 at 13:15

Let's start with the most important stuff. Here is a quick check list in order to verify solution maturity:

  1. Can a result be auto-generated for any given piece of code?
  2. Can it be continuously updated without any need in additional "adjustments"?
  3. Does the solution support deterministic and simple layouting?
  4. Can it visualise a simple switch-case with three or four options?
  5. Does it allow to handle versioning and visualise difference between two versions?

These "requirements" might look like an overkill, but without that users eventually will be forced to deal with the code and all fancy visualization tools will become useless. Anyway, let's check a free form flow-chart idea. Here is 8 years old free form DSL structure visualization:

enter image description here

Let's check it:

  1. It can, but it might be really hard to layout items properly, so user will need to adjust the structure.
  2. Potentially yes, but it is highly likely layout will be broken.
  3. No, there will be many ways to layout nodes and you'll need to investigate some special articles (like, for example, Drawing rooted trees in linear time by Christoph Buchheim, Michael Junger and Sebastian Leipert) in order to make sure user will not spend seconds waiting for a structure to appear.
  4. No.
  5. No. Layout is complex, so it will be really hard to compare current and previous structures.
    Below I'll try to summarise my experience. I'm doing that just for fun, so feel absolutely free to ignore this answer.

Lessons learned

Example above shows visualization of pretty complex network protocol decoding logic. Despite the fact it is simple it still provides decent high-level overview and simplified navigation. The problem is it requires user to properly layout elements in order to make the whole structure readable.

  • Lesson 1: Pretty much all flow chart examples looks readable because they are simple. Real-life structures are way more complex, so corresponding flow-charts will be complex too and lots of additional tricks will be needed to help users read those structures.

  • Lesson 2: Users do not like/want to spend their precious time doing stupid layouting.

  • Lesson 3: A layout, created by a user, should not be altered by a system.

So there is pretty important conclusion: avoid bothering user with the layout. Also there are several quite valuable rules:

enter image description here

Communicating Design: Developing Web Site Documentation for Design and Planning

You'll find lots of interesting hints in that book, but I would like to highlight the importance of choosing proper direction. Naturally you can use canvas, draw anything you want and let user drag it, but it is better to simplify everything and follow usual scroll pattern.

enter image description here

Check D3.js Drag and Drop, Zoomable, Panning, Collapsible Tree with auto-sizing.

BTW, there is classical and simple flow chart representation called Nassi–Shneiderman diagram

enter image description here

Modern implementation of such approach might be quite useful, but it depends. I bet it does not look very straightforward and intuitive from the very beginning :)

Alternatives

Flow chart is not the only approach. Let's look around for a second. There are a lot of different solutions already available, just check visual programming

enter image description here

I would suggest to check:

No magic there, if you have initial complexity you'll definitely see it later:

enter image description here

enter image description here

Enhancing flow chart

Wikipedia has simple flow chart example. I will use it to demonstrate proposed approach.

I'm not going to present anything special. Just a simple idea how to simplify rendering and make it uniform and flexible.

enter image description here

Please note, this is something like a wire-frame just to illustrate the idea. Elements are clean and readable. It is easy to identify flows and navigate through them.

Rendering is deterministic and pretty straightforward. Basically it is all about columns and rows:

enter image description here

Switch-case construction is possible

enter image description here

Execution flow is easily traceable

enter image description here

Elements can be grouped

enter image description here

Columns and rows can be folded

enter image description here

In some cases "flow stretching" might be required

enter image description here

In some other cases flow stretching can be used to enhance readability.

Versioning and diffs

Having deterministic and stable layout it is pretty easy to compare two different versions of the same algorithm.

enter image description here

Moreover, we can use "flow stretching" in order to make diffs highly readable and mimic similar tools used for textual sources:

enter image description here

Let's summarize

  1. Can a result be auto-generated - yes, easily
  2. Can it be continuously updated - no problem at all.
  3. Deterministic and simple layouting - yes, no manual adjustments are required
  4. Can it visualise a simple switch-case - yes
  5. Does it allow to handle versioning and visualise difference - yes it does. BTW, three way diff is also possible.

Alternative solution Almost for any complex language simplified DSL can be introduced. I would say it should be much easier to design simplified language on the top of the current one.

Having that you can get everything mentioned above virtually for free.

Thanks a lot of the question :)

  • Great Answer! You mention a lot of good points I didn't even consider and I like the "collapse unneccessary parts" convecept. Not sure If I'll be able to create these diagrams by a programm as I intendet - but your answer will surely help a lot of people with a similar question! – Dennis Jan 26 '15 at 7:45
  • 1
    Thank you, I hope so :) BTW, I wasn't trying to show a final solution. Just wanted to highlight it is crucial to avoid free form layout and save some room for maneuver. I've been developing third such system for a while and can only say readability is a key. Anyway, it was obvious from the very beginning :) – Renat Gilmanov Jan 26 '15 at 8:08

Whether my answer is useful will depend on the skillset and time available for the one doing this, so it may not be for everyone. But if you're able to take this solution it certainly has some upsides.

Document with automated unit and/or integration tests. Create a basic test harness for the script, and present them as a list of "business rules" or "use cases" for your business users.

There are several advantages to this approach:

  • You can have a good degree of confidence they're correct: you can run them!
  • They may surprise you: you may write a test that you expect to be green but it turns out red (or vice versa), because you didn't understand the script completely (yet).
  • They will be useful if changes are to be made: tests give you confidence that one change doesn't break another scenario. As such it will also save time in the long run.

There are a few disadvantages too:

  • It may take some effort to make the list of "Business Rules" (tests) insightful to business users; sometimes a visualization (e.g. flow chart) will be easier to understand.
  • Though the approach is precise and will save time in the long run, it's not very useful if you have very limited time. E.g. if you have one morning to read the script, and the afternoon to write a report, then this approach will not work. In your question you don't provide the level of detail and correctness you aim for, but it'll depend a lot on that.
  • You need to be familiar with writing automated tests for such scripts, or be able to include learning time in the alotted time.
  • Unit tests may or may not be possible (or at least not without some refactoring), depending on how the script is structured. (To be honest, the form you mention, with "lots of if/else structures" is probably not very well suited.). Integration tests should then still be possible.

Like I said, this approach may not be for everyone. But if you're able to do it like this, it comes with a few nice perks.

  • I very much appreciate your answer, especially since it lists a lot of negative aspects as well. Sadly many of them apply to my situation: A) I don't have much experience with tests at all. B) I don't think my users will accept tests as they want a view on the entire program and not just a few test cases. I'll edit my question to make things more clear. Sorry I missed some points in the first place. – Dennis Jan 19 '15 at 8:42
  • 1
    Thanks for your kind comment. I understand my solution may not be for you, nonetheless I'll leave it up there for others that may have use for it. – Jeroen Jan 19 '15 at 9:17
  • Note by the way that I didn't want to imply "just a few test cases". You can get quite good coverage with automated tests. In fact, with tests there's even a metric (though debatable how useful it is); with a flow chart or list of business rules measureing is a lot harder. If I have time tonight I may update my answer a bit on that. – Jeroen Jan 19 '15 at 9:19
  • Sorry, -1. Writing more code instead of reverse-engineering and visualizing the program flow to outsiders. It does not sound like an answer to the question put by OP. – Kromster Jan 21 '15 at 6:08
  • @KromStern Sorry you feel this answer is bad advice. IMHO writing a test harnass is reverse-engineering. Further, visualizations were not deemed necessary by OP as indicated by his comment to the question. Also, OP's comment to my answer here suggests (to me at least) that it does answer the question, even though due to circumstances it's not an option. – Jeroen Jan 23 '15 at 11:40

After giving this much thought I am convinced that any attempt to make the flow of an entire program easy to understand by everyone will end up being harder to consume than the program code itself. All the code visualizations posted in this thread are harder to read than lines of text.

Code is already short and to the point and the reason we use it to tell computers what to do. Don't you think that if there was an easier way to represent the flow of a program then that is what we would be using to program in the first place?


There are, however, ways to make code easier to navigate.


Step 1: Make the statements as linear as possible

It is more clear to write lines of code that repeat in a function call or loop so that the entire program is a list of variable declarations or conditional assignments (by default the conditional is true and the assignment will occur when no IF statement is given)

Step 2: Replace symbols with words

Pseudocode may be a little bit easier to read so try and convert the native language into something more like English. For example, there is no need to show semi-colons or curly braces and logic operators like && are easier to read as AND. Trying to make a flowchart or table will almost always be harder to read than simple lines of text.

enter image description here

Step 3: Make the long list of instructions easy to search

Highlight the names of variables as the user types them

enter image description here

Collapse unmatching lines of code into links that can be expanded to show context when clicked

enter image description here

enter image description here

There are a few other things you could do to improve this interaction.

  1. Make links to show all conditional variable assignments or show all variable declarations etc.

  2. Allow input of starting values for each variable so the user can see how the values change inline

  3. Highlight conditional IF statements red or green to indicate true or false when that can be determined

I hope this solution will get more ideas flowing. (pun intended)

  • 1
    Really great answer with a lot examples! If my users didn't ask specificly for "no code!" I would prefer this approach. Still a very valid answer for my questions (sadly, just not for me) Thanks! – Dennis Jan 26 '15 at 7:41
  • lines of text don't have to be code - if X > 10 then add 5 to Y - basically it comes down to what version of pseudo code can everyone read like a book. graphs and visualizations get in the way of assignments and flow – DaveAlger Jan 26 '15 at 18:03

One difficulty with this task is that simplifying the code for readability will generally make it represent only simple concepts. As such I think the best format would be something that had a way to adjust what the user was currently looking at depending on what their interest was.

Specifically, you could make a flowchart which would show only the most basic functions of the program at its outward layer, but had selectable elements. On clicking one, it would expand to show another flowchart corresponding to the functions of that element.

For example:

Outer Layer

outward layer

On Clicking End Element

end element

I'm not sure how possible this will be, the nature of programming seems to me that it is very difficult to conceptualize the entire flow of a program and many possible outcomes / paths in great detail.

Basically I'd like to write a documentations / program / excel sheet / whatever which is able to answer questions like "Under what conditions will the printed price field include VAT?"

I like this idea the best, it allows people to access the information they need discretely, a bit like stack exchange. I think a flow chart is essential just reproducing the programme to run on a human instead of a computer. And there are good reasons we get computers to do this sort of work.

Of course I'm assuming you do want people to understand the programme not just be satisfied that you do. Having more people understanding the process could lead to you loosing some autonomy and decision making power in the project. See bike shedding.

The problem with flow-diagrams, is that they are not Turin complete... :P

You cannot represent, for example, a child in a flow diagram - at least not in any detail. You could represent their morning routine, the route they take to school, or even their small circle of friends - but you are not anywhere close to representing the child itself. Mapping out all outputs based on all possible inputs to child.exe would create a mesh of lines so thick, by the time you finished drawing it the child would be an adult and very concerned as to why you're taking such great interest in their activities.

Programs are a lot like children - except programs have purpose. You should ditch flow diagrams for your program and use videos, because its much easier to understand a child's behaviour through video than flow-diagram.

Watch this: https://www.youtube.com/watch?v=8aGhZQkoFbQ

Get inspired by this: http://latentflip.com/loupe

And then decide if you're going to make a slideshow, or a smaller demo-program which just tells you what the main program would have done if it had been asked the same question :)

Your Answer

 
discard

By clicking "Post Your Answer", you acknowledge that you have read our updated terms of service, privacy policy and cookie policy, and that your continued use of the website is subject to these policies.

Not the answer you're looking for? Browse other questions tagged or ask your own question.