Clear questions and runnable code
get the best and fastest answer
You have asked an interesting question and I would like to interpolate a bit. The question is not:
You should be able to draw the 'big picture' of your approach on one page. This picture might be complex, but you should be able to point to it and explain what each part of the picture is supposed to do. This is the thing to focus on first.
The best way to draw this big picture is to use a whiteboard and iterate versions of it until you think it is perfect. Be sure to put your name and the date on the picture.
Now for the tricky part. You need to get the picture onto some paper. The best case is that you have a whiteboard with a printer attached to it. If you don't have that tricky bit of technology, transcribe the board by hand on to a sheet of paper in ink. When people see your architecture written in ink, they will be intimidated. This is good. You don't want some idiot rearranging your work for no good reason.
Then code like hell and make as quick and dirty a prototype as you can. Use real test data provided by your customers as a demo. Show it to your customers and have them tell you what they *really* wanted. When they ask, 'can it do this or that?' don't worry about how much effort different approaches will take. Just say "Sure, it can do that! The important thing is that's what you really need." Think through the implications with the customer as best you can, throwing caution to the wind. Keep a list of every single request for change.
These conversations with users will tax your ability to back off and see from the customer's point of view. Don't worry that minor changes may have major impact on your code. Don't try to defend your design decisions at this point, just try and see how the system could truly be improved.
Next you have to decide if you can salvage your proto or if it is best to start over. Since it is your first big project, you'll probably need to start over. No big deal. Look at the big picture you drew. Is it still right? If it's wrong, don't fix it, file it under 'prototype' and redo the whole thing. You did it in ink anyway! Now, go through your list of changes and see if every single one of them is all fixed up in the new system. You might find that a few of the requests really don't make sense in the new system. Go back to your customers and see if these items can be worked out another way. Emphasize to the customers that you aren't looking for compromise, you're looking for the best solution possible. Not necessarily easy for you to implement, but at least possible for you to implement within your constraints.
This time you code it carefully. Use the advice given in the other responses to your question, especially using revision control and building test code. Use revision control from the start. Continually improve your coding practices throughout the development of the prototype. In the second version, back off and simplify your coding style a bit, using only things that worked well in the prototype. Don't get grandiose and try to solve a larger problem or use new untested techniques in the second system, instead solve the problem in a simple yet comprehensive way. You'll notice that the code gets larger and more complex as you add all the necessary error checking and handling of special cases, so start simple to keep the code from becoming too big of a mess.
Show it to the customer again. Find out if this system is better than the prototype. It might not be! You might want to iterate again, this time keeping true to your original vision. This isn't so much trouble; since you've coded the thing twice now, you're getting good at it!
To summarize, my advice is to draw nice system diagrams by hand. Build a proto, get feedback, start over. Understand the system from top to bottom and be able to sketch how it works at every level. Work hard and keep the design of the whole system fresh in your mind.
Imagine that your bosses' bosses' bosses' boss is coming to review your work one day. You have a wad of slideware about the system to show to the Big Cheese. The slides have been reviewed and sanitized for political correctness. But when you get to the meeting, the big boss says, "I've been looking at slides all day and I'm tired. Just draw me a picture of the system and explain to me how it works." You'll be able to think and draw on your feet while speaking clearly. That's looking good!
It should work perfectly the first time! - toma