Suggestions for writing a code flowchart

Question

I'm nearing the end of my internship this summer, and I've developed a tool for my mentors that involves primarily PHP, MySQL, JavaScript (jQuery). Does anyone have any templates or suggestions or links on creating an easy to read document showing the code structure of the program and the relationships between the files?

These guys are programmers, but have not had much experience in any of the languages above, so I'd like it to be relatively simple.

---

Edit:

Seems like some type of flowcharting is the way to go (which makes sense). Do you start with every class file on a page? Or do you start one by one, and figure out every detail and branch out, rearranging it as it gets more complicated.

Answer 1

Mind Mapping might be of some help here, there are some free tools that I can recommend, like FreeMind or XMind.

Answer 2

I'd start by describing what the software does (functional specification), and how to build, run, and test it: http://stackoverflow.com/questions/400382

After you've done that, you can add pointers from your functional spec into the source code, to identify which bits of source code help to implement which bits of functionality.

[When I say 'pointers', I mean that in a section which identifies/describes some functionality, add the URLs and/or names of the corresponding source code.]

Answer 3

You might check out Doxygen, which does mark up PHP documentation. If dot is available, Doxygen can automatically generate dependency graphs for files, call graphs for functions, and ancestry graphs for classes as well.

But, Doxygen doesn't have any exact support for documenting MySQL source. It appears that there is some popular perl script for documenting Javascript code, though.

You might be interested in seeing some sample Doxygen-generated documentation as well.

Answer 4

Search for any free UML tools, or if you have access to Microsoft Visio use it to create UML diagrams.

Answer 5

I recommend using OmniGraffle. It's an OS X application, but it's phenominal.

http://www.omnigroup.com/applications/OmniGraffle/

Answer 6

I've done this for a lot of my projects. In fact, now when I start work on an existing one I've learned to make some sort of flow chart for my own reference, and then check it into the repository.

I prefer a flowchart type of diagram (maybe in addition to what you have in mind). I just use Open Office and draw circles, rectangles, triangles, etc., for the various pieces & decisions. If you make one and then copy it, changing the text as needed, it's not too time-consuming. Same with the arrows, just make a lot of them then move them around where you want.

I've tried looking for a tool that does this but if it's significantly easier to use than OO it tends to be buggy and crash. If it's stable, it's not any been any faster and maybe didn't have even as many drawing options as OO does.