Best way to display code to non-programmers

Question

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.

Answer 1

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.

Answer 2

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:

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:

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.

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

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

I would suggest to check:

• Yahoo pipes
• Blockly

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

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.

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:

Switch-case construction is possible

Execution flow is easily traceable

Elements can be grouped

Columns and rows can be folded

In some cases "flow stretching" might be required

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.

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

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 :)

Answer 3

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.

Answer 4

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.

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

Highlight the names of variables as the user types them

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

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)

Answer 5

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

On Clicking End Element

Answer 6

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.

Answer 7

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 :)