What tools do you use for outlining projects?

Question

Whenever I start working on projects that are complex enough that I can't keep it all in my head at once I like to outline how the app should work... I usually hack something like this out in a text editor:

# Program is run
#     check to see if database exists
#         create database
#             complain on error, exit
#     ensure database is writable
#         complain to user, exit
#     check to see if we have stored user credentials
#         present dialog asking for credentials
#             verify credentials and reshow dialog if they're invalid
#     show currently stored data
#     start up background thread to check for new data
#         update displayed data if new data becomes available
#     ...
# 
# Background service
#     Every 15min update data from server
#     Every 24 hours do a full sync w/ server

Et cetera (note: this is commented so SO won't parse it, not because I include it as comments in code).

What I'm wondering is how you guys do this. Are there any tools for outlining a program's flow? How do you describe complex projects so that when it comes time to code you can concentrate on the code and not the design/architecture of all the little pieces?

Answer 1

I use GraphViz if I need to sketch out such simple diagrams - the DOT language is lightweight and diffs very nicely when I compare versions of the diagrams.

I blogged about this with an example a few months ago with an example showing a more complex architecture diagram.

I've also just added a blog post with a zoomed-out diagram that shows a large program flow, to give an idea of how a GraphViz flow might be composed. I haven't the time to obfuscate all the text so just put it up there as a picture at low res to give the impression of the architecture without being able to zoom in to see readable details.

This diagram was composed by hand after a bunch of grepping to get launches. To avoid taunting you too much, here are some excerpts of the DOT text that generates the diagram.

digraph windows {
 rankdir=LR
 label="Windows Invoked\nby controls and menu items"
 node[fontsize=12]

/* ENTRY POINTS */
 wndMainMenu[shape=box color=red fontcolor=red]
 DEFAULT_WINDOW[LABEL="DEFAULT\NWINDOW" shape=box color=red fontcolor=red]


/* WINDOWS */ 
 node[shape=box color=black fontcolor=black style=solid]
 App
 wndAddBill [label="Add Payable\nwndAddBill"]
 wndAddCustomer [label="Add a Customer\nwndAddCustomer"]

...

/* WINDOW INVOCATION */
 node[shape=oval color=blue fontcolor=blue style=normal]
 edge[fontsize=10 style=normal color=blue fontcolor=blue]

 wndPayBills_bvlNewBill -> wndAddBill 
 wndAddCustomer -> wndAddCustomer_save001
 wndManageDrivers_bvlNewCustomer -> wndAddCustomer 

alt text http://www.aussiedesignedsoftware.com/img/WindowLaunchesZoomedOut.png

Answer 2

Emacs M-x outline-mode

Or, paper.

p.s. this is a serious answer.

Answer 3

Basically what you are trying to do is extract the information and use-cases in Given-When-Then format. refer http://wiki.github.com/aslakhellesoy/cucumber/given-when-then. This approach solved both problems.

• comprehension of domain and edge cases
• outlining of the solution so you know what to work on next in addition to where to start

Answer 4

For anything related to documentation: Wikis, wikis and more wikis! Easy to read and most important, easy for anyone to update.

My favourite one: Trac (much more than just a wiki anyway)

Answer 5

Are there any tools for outlining a program's flow?

Your top comments ("Program is run") could be expressed using a "flow chart".

Your bottom comments ("Background service") could be expressed using a "data flow diagram".

I don't use flow charts (I don't find they add value compared to the corresponding pseudo-code/text, as you wrote it), but I do like data flow diagrams for showing a top-level view of a system (i.e. the data stores/formats/locations, and the data processing stages/IO). Data flow diagrams predate UML, though, so there aren't very many descriptions of them on the 'net.

Answer 6

I like sequence diagrams for anything in the OO realm. There are several nice ways to create sequence diagrams without spending all your time pushing polygons around.

First, there are some online sequence diagram generators that take textual input. For one example, see WebSequenceDiagrams.com.

There's also a nice Java based tool that takes textual input and creates diagrams. This is well-suited for integration into your build process, because it can be invoked directly from ant.

Answer 7

If something is complex I like pictures, but I tend to do these by hand on paper, so I can visualize it better. Whiteboards are great for this.

I break the large, or complex app, into smaller parts, and design those out on paper, so I can better understand the flow between the parts.

Once I have the flow between parts done, then I can better design each part separately, as each part is it's own subsystem, so I can change languages or platforms if I desire.

At that point, I just start working on the application, and just work on one subsystem at a time, even though the subsystem may need to be decomposed, until I have a part that I can keep in my head.

Answer 8

1. Use Cases
2. Activity Diagrams
3. Sequence Diagrams
4. State Machine Diagrams
5. Class Diagrams
6. Database Diagrams
7. Finally, after those are done and the project is looking well defined, into Microsoft Project.

I like to keep this flow as it keeps things well documented, well defined and easily explainable, not to mention, it's simply a good process. If you are unsure on what these are, look at my answer in here giving more information, as well as some links out.

Answer 9

I recommend using UML There are various depths you can go into when designing. If you take UML far enough, most UML applications can auto generate the basic framework of your code for you.

Typically I rely on loose UML, generating use cases, use case diagram, class diagram, component diagram, and have started using sequence diagrams more.

Depending on the project a whiteboard or notepad works, but for a project of reasonable size and time, I'll do everything using ArgoUML I have enjoyed StarUML in the past, but it's Win32 only, which is now useless to me.

A great book on the subject is Applying UML and Patterns: An Introduction to Object-Oriented Analysis and Design and Iterative Development (3rd Edition) - [978-0131489066]

I had to pick it up for a college course which did a crumby job teaching UML, but kept it and have read it a time or two since.

This is also worth checking out: Learning UML 2.0 - O'Reilly - [978-0596009823]