Design Documentation

VisualAge for Java can provide a very good way to help document your design!

You won't be maintaining that program forever...

Realize it or not, you won't be the one who maintains your program forever.   Or at least you shouldn't want to be the one who maintains that program forever.  Don't you want to go off and program new stuff, and leave the minor tweaks to someone else?

But if I'm not maintaining it, I'll have to (gack) document it!

Of course you'll need to write documentation (as well as comment your code) for someone else to easily understand what you intended to happen in your code.  A maintenance programmer generally won't have time to thoroughly study all of your code to figure out what it's doing.  Design documentation is critical to help him (that's an inclusive "him" for all you "him/her" types out there) target the area of the program that he (again, inclusive) really needs to look at.  Always ask yourself: "If I didn't know this (well-structured) wad of code, how would I know where to start looking to fix a problem?"

So how can VisualAge help reduce my documentation burden?

Simple.  Use the Visual Composition Editor!

When programming GUI applications, or even non-GUI applications, you can use the Visual Composition Editor to essentially draw the interactions between components in your program.  In most cases, this can save time programming event logic.  In other cases it may take slightly longer than hand coding.  However, those connections stay long after you've washed your hands at the code.  A maintenance programmer can say to himself "hmm, things don't work quite right when the user uses the "add" button.  Hey! I'll look at the connections from the add button and see what actions are triggered!"

This can really assist the maintenance programmer, and you didn't have to write a separate document stating what actions you set up for that action button!

But I still write code, right?

Obviously you'll still need to write code for your application to work.  But I offer a few words of advice to help make your design more obvious:

But now I have three billion connections on the screen!

This can be daunting (and can hurt performance when loading into the Visual Composition Editor.)  But, as I stated above, unless you want to be tied to that code for the rest of your life, make it easy for Mr. Maintenance Programmer!!!  There are a few things you can do to help this: