Best Design Practices

[rasinc]

I wasn't trained as a programmer and have never really gone through best practice training so I have a couple of questions if I could. Sorry this is a long post but I have been trying to figure this out the proper way for quite a while now.

I have been doing VB6 programming for about 9 years doing my own stuff and have a couple of programs commercially available in a small market. I think to further develop and take advantage of a changing market, I need to get more sophistocated in my programming. I think that means I should probably start looking at VB.NET. So I am doing some background stuff, looking at controls available, syntax, etc. I have the Express versions of 2005 and 2008 but have not done too much yet with them. I did take a course almost 4 years ago now on VB.NET 2003 Standard but did not do any production programming with .NET.

My question today revolves around the design work done before programming. I currently have a product that I wish to rewrite rather than convert (I have heard it is best to rewrite rather than allow converters to do the work and yes I have tried converting and can make some stuff work but I don't want to debate this issue today . In the past, I roughly sketched (yes, in pencil) a form design and a couple of features, then coded and changed as I saw the need once I saw it working. This method was used because when I started I had no idea what I was doing. Now I can see further ahead in my programming so I want to look at proper design concepts before I program.

I am looking at writing some documents that will show the current form image, then list the features of the current setup including where the form is called from, what happens on loading the form before it is seen, then listing all controls and what happens during user interaction (eg. click, mouseover, enter and leave validation, etc.). The idea here is to document properly what the current version of the program does.

Then I thought I would add sections to indicate what should happen in the new version. For example, a new form may need to be added, or current forms changed so I would indicate those changes, then for each new control, list what needs to happen from a feature point of view. For each new form create a new section, for old ones, add on to show changes.

Lastly I was thinking of then further expanding on the changes section to write some (hopefully) well thought out coding (pseudocode) to outline the order and identify variables and logic.

Am I on the right track? Is there something else I should be considering? I've never seen how people write documents like this. Does anyone have any advice or document template samples they would be willing to share? I would really appreciate it so I can try to reduce the efforts I have made in the past that should have been less work and more stable in the end. TIA

[techgnome]

Am I on the right track? Is there something else I should be considering? I've never seen how people write documents like this. Does anyone have any advice or document template samples they would be willing to share? I would really appreciate it so I can try to reduce the efforts I have made in the past that should have been less work and more stable in the end. TIA

Only you can answer if you are on the right track. Every shop has their own standards and processes for stuff like this. I do commend for you taking the initiative to doing it on your own, especially to that level of detail. You'd fit right in here.... Because that's basically how we do ours here.... with some tweaking. If a design doc has already been done, we don't re-document what the section does. We just write up the portions that are going to change, then highlight the changes. If there isn't an existing document, then we document all of the current functionality, and insert the changes as we go along, again highlighting just the changes. We note what will be added, what's changing, what's being deleted. As for screens, we use Visio to document screen changes and proposals.

I can't share our templates because they are proprietary, and constantly changing.

The hard part is maintaining the design doc during development. It's inevitable that some part of the design just simply won't work, and so you make changes to the code.... don't forget to make those same changes in the design - it helps to do that as you go along and not after the fact.

-tg

[penagate]

When you say ‘design’, do you mean product architecture, or GUI design?

[rasinc]

techgnome - thanks for the reply and the advice on maintaining documents when things change during programming. I had not gone that far with my concepts. It's nice to see some of what I came up with is useful. I have never been able to figure out how to use Visio so I will have to look into that again. I think I have the 2000 version.

penagate - thanks for your reply also. You really know how to make a guy think. Having never been really trained as a programmer I am not completely sure what comes under the title of architecture. However, the GUI may change in a newer version so I am documenting the current forms using images of the current setup and will indicate which changes are necessary. So what does architecture cover? Is it just the language used? Does it include the .NET framework? Or is it more basic like what forms, modules, class modules, controls, etc. are going to be used?