1. Software Design Process
I have been working on a fairly large software project, with database and
display components, and the all-important user interface. Now my coding
method is ad hoc at best, and I haven't used any particular system of design
or coding.
I managed to get the display component of this system fairly complete, and
some of the user interface directly related to the display component, but
when I started coding database and more advanced user interface stuff - in
my ad hoc way - it all just ground to a halt.
Now, I can see how it might benifit having some kind of perfunctory overall
design and process to follow. Can anyone suggest ideas or resources for how
I might go about doing this? This is a one-man project, so I don't imagine I
would need something as complicated as ISO/IEC 12207 compliance...
To the Euphoria heavyweights, how do you guys plan your projects?
=====================================================
.______<-------------------\__
/ _____<--------------------__|===
||_ <-------------------/
\__| Mr Trick
2. Re: Software Design Process
On Thu, 12 Jun 2003 14:08:42 +1000, <mistertrik at hotmail.com> wrote:
>
>
> I have been working on a fairly large software project, with database and
> display components, and the all-important user interface. Now my coding
> method is ad hoc at best, and I haven't used any particular system of
> design or coding.
>
> I managed to get the display component of this system fairly complete,
> and some of the user interface directly related to the display component,
> but when I started coding database and more advanced user interface stuff
> - in my ad hoc way - it all just ground to a halt.
>
> Now, I can see how it might benifit having some kind of perfunctory
> overall design and process to follow. Can anyone suggest ideas or
> resources for how I might go about doing this? This is a one-man project,
> so I don't imagine I would need something as complicated as ISO/IEC 12207
> compliance...
>
> To the Euphoria heavyweights, how do you guys plan your projects?
Firstly, how much I weigh is not for public information.
Secondly, "ouch!" - I feel your pain.
---------------------------------
Welcome to System Development 101.
---------------------------------
There is no easy way out - you have to work at it. Unless your system can
be totally specified on a single piece of A4 paper and be understood by a
8th grader, you should stop now, and put things into order.
On the assumption you don't want to work on the same system forever before
its released, you need to know when to stop working on it. The easiest way
is to write a list the things that the system MUST be able to do. Then stop
working when the system can do all of them.
This is the Requirements List. Most likely, a simple list will not
adequetely express, in an unambiguous manner, the full requirements. So,
for each item in your WRITTEN DOWN list (yes, writing it down is important)
you ought to add enough detail so that, hyperthetically, somebody else
could write your system for you. This is a balancing act, for sure. It is
easy to write too little detail as it is to write too much. Remember to
describe WHAT the system should deliver rather than HOW it should deliver
it.
One useful technique for the UI aspect of your system, is to write down the
'use cases'. That is, how a person will actually use the system to do each
single, very specific, thing. These are usually written as a set of actor-
action-effect statements. For example, if I'm describing how to use IE to
view a web page.
Actor Action Effect
-------------------------------------------------------------------
1. User Click in Address Bar Cursor moves to Address Bar
2. User Type in URL The URL is displayed in AddrBar
3. User Press the [Enter] key. The 'world' icon starts moving
4. System Locates the web page The web page is displayed.
Often you will have a pre-requirement specified too. In this example, that
might be that IE has been started running (this might be a link to another
use-case).
A use-case will always have the primary process flow. It may also have many
alternate flows that are there to deal with exceptional circumstances. In
the example above, you might also have ...
Exception after (4): Error message 'page not found'.
5. User Check the spelling of the URL and correct if needed.
When you have use-cases documented, testing the system becomes real easy.
Just follow the use-cases. Any unexpected effects might be bugs or missing
use-case material.
Don't build any production quality code until you have the requirements
specified. However, one of the better ways of understanding what the
requirements are is to build prototypes. Demo programs, or sample programs,
that help you play with your ideas until you fully understand what you (or
your clients) want. Never convert a prototype into a production system.
Always start a production system from a clean slate. The prototype is a
learning method where mistakes and dead-ends are expected. You are allowed
to
compromise quality in protypes. However, these don't convert well into
production code.
To make sure that your requirements are useful, get somebody else to
inspect them and suggest improvements. In nearly every case, a second pair
of eyes will find mistakes or improvements that you never would have found
until too late.
After you have your requirements documented, you really should prepare your
test cases, but this is best left for an experienced tester. Developers are
the worst testers of their own product. Its a huge psychological effort to
actively try to find bad things about your 'baby'. A common statement from
developers is "Oh come on! No-one would do that in normal usage!". BZZZTT -
Wrong!
Time to address System Architecture. Otherwise known as "how it all hangs
together". Write down, usually with plenty of diagrams, the conceptual
components of your system. Especially note what information the components
need from each other. Mark in any 'external' components too. The reason for
doing this is two-fold. One is to test out your concepts about what the
system is trying to achieve and how you can get to happen. And the second
is to have a sort of blueprint that you can continually comeback to to see
if you are on track.
Generally speaking, you should be developing N-Tiers applications. By this
I mean that your database and/or file-access components should be
independant from your 'business' logic, which should be independant from
your User Presentation code. Theoretically, you should be able to replace
any of these tiers (layers) without having to change a single line of code
in any of the other layers. For example, you may write your system using
the EDB, but later you replace this with MySQL. If you do this, you really
shouldn't have to change the code that displays stuff to the user, or the
code that processes the data. To achieve this level of N-Tier-ness you have
to give considerable thought about how to separate the functions of your
code and how to pass data between them. There is no one answer to that - it
all depends on your architecture and other constraints.
Next, make some design notes. Write down HOW you are going to meet the
requirements. This is a form of technical specification. This stuff is
invaluable when it comes to maintenance time. It doesn't take long before a
developer comes back to their own code and wonders "what the **** is this
section of code trying to do?" A good place to put this documentation is in
the code itself, especially if you can use some tool to extract it into a
transportable format.
Finally, you get to write some code. By now, you know the system inside out
and code-writing is the easy part - almost tedious. If so, that's a good
sign. It means that most of the mistakes have already been made and
corrected.
For each of the 'deliverables' of your system - the requirements,
architecture, design, and code - it ALWAYS pays to have somebody else
inspect them before getting too deeply into the next stage. Finding
mistakes as early as possible, is a good rule.
I know I've made this sound like it takes a lot of paperwork and time
before you can see anything for your efforts, but no-one says you have to
do each stage in its entirety before progressing to the next stage. If you
like, you can take 'baby steps'. For example, create a requirements spec
that only has a broad target, then go through the stages to implement that.
This might all be done in a single day. Then go back and expand on the
requirements, and repeat in this incremental way. Some people find that
doing development like this is fun because you get to have a lot of variety
and get results often. It is also easy to change direction because you can
detect possible direction changes faster and have smaller amounts to
rework.
Of course, overall you really should prepare a plan - one with specific
tasks and timelines in them. You can use this to keep spurring yourself to
action. They can also (and should also) be updated daily based on what you
have learned during the previous day. Add tasks, revise expectation, or
whatever so that the plan always reflects your best guess as to what is
happening with your project. An important thing to remember with project
plans is that they are trends and not destiny.
I guess that's enough for now 
--
cheers,
Derek Parnell
3. Re: Software Design Process
Thank you VERY much. :o)
As for a second pair of eyes, I think I've just found a job for my
not-too-technical friend who's been bugging me about finishing this project!
=====================================================
.______<-------------------\__
/ _____<--------------------__|===
||_ <-------------------/
\__| Mr Trick
>From: Derek Parnell <ddparnell at bigpond.com>
>Reply-To: EUforum at topica.com
>To: EUforum <EUforum at topica.com>
>Subject: Re: Software Design Process
>Date: Thu, 12 Jun 2003 17:26:37 +1000
>
>
>On Thu, 12 Jun 2003 14:08:42 +1000, <mistertrik at hotmail.com> wrote:
>
>>
>>I have been working on a fairly large software project, with database and
>>display components, and the all-important user interface. Now my coding
>>method is ad hoc at best, and I haven't used any particular system of
>>design or coding.
>>
>>I managed to get the display component of this system fairly complete, and
>>some of the user interface directly related to the display component, but
>>when I started coding database and more advanced user interface stuff - in
>>my ad hoc way - it all just ground to a halt.
>>
>>Now, I can see how it might benifit having some kind of perfunctory
>>overall design and process to follow. Can anyone suggest ideas or
>>resources for how I might go about doing this? This is a one-man project,
>>so I don't imagine I would need something as complicated as ISO/IEC 12207
>>compliance...
>>
>>To the Euphoria heavyweights, how do you guys plan your projects?
>
>Firstly, how much I weigh is not for public information.
>
>Secondly, "ouch!" - I feel your pain.
>
>There is no easy way out - you have to work at it. Unless your system can
>be totally specified on a single piece of A4 paper and be understood by a
>8th grader, you should stop now, and put things into order.
>
>On the assumption you don't want to work on the same system forever before
>its released, you need to know when to stop working on it. The easiest way
>is to write a list the things that the system MUST be able to do. Then stop
>working when the system can do all of them.
>
>This is the Requirements List. Most likely, a simple list will not
>adequetely express, in an unambiguous manner, the full requirements. So,
>for each item in your WRITTEN DOWN list (yes, writing it down is important)
>you ought to add enough detail so that, hyperthetically, somebody else
>could write your system for you. This is a balancing act, for sure. It is
>easy to write too little detail as it is to write too much. Remember to
>describe WHAT the system should deliver rather than HOW it should deliver
>it.
>
>One useful technique for the UI aspect of your system, is to write down the
>'use cases'. That is, how a person will actually use the system to do each
>single, very specific, thing. These are usually written as a set of actor-
>action-effect statements. For example, if I'm describing how to use IE to
>view a web page.
>
> Actor Action Effect
>
>Often you will have a pre-requirement specified too. In this example, that
>might be that IE has been started running (this might be a link to another
>use-case).
>
>A use-case will always have the primary process flow. It may also have many
>alternate flows that are there to deal with exceptional circumstances. In
>the example above, you might also have ...
>
>Exception after (4): Error message 'page not found'.
>5. User Check the spelling of the URL and correct if needed.
>
>
>When you have use-cases documented, testing the system becomes real easy.
>Just follow the use-cases. Any unexpected effects might be bugs or missing
>use-case material.
>
>
>Don't build any production quality code until you have the requirements
>specified. However, one of the better ways of understanding what the
>requirements are is to build prototypes. Demo programs, or sample programs,
>that help you play with your ideas until you fully understand what you (or
>your clients) want. Never convert a prototype into a production system.
>Always start a production system from a clean slate. The prototype is a
>learning method where mistakes and dead-ends are expected. You are allowed
>to
>compromise quality in protypes. However, these don't convert well into
>production code.
>
>To make sure that your requirements are useful, get somebody else to
>inspect them and suggest improvements. In nearly every case, a second pair
>of eyes will find mistakes or improvements that you never would have found
>until too late.
>
>After you have your requirements documented, you really should prepare your
>test cases, but this is best left for an experienced tester. Developers are
>the worst testers of their own product. Its a huge psychological effort to
>actively try to find bad things about your 'baby'. A common statement from
>developers is "Oh come on! No-one would do that in normal usage!". BZZZTT -
>Wrong!
>
>Time to address System Architecture. Otherwise known as "how it all hangs
<snip>
>
>
4. Re: Software Design Process
- Posted by rml at rubis.trix.net
Jun 12, 2003
Derek and "Mr Trick" ;
This text could be part of the Euphoria manual! :>)
Things like this make this list very useful.
Good question, excellent answer.
Rubens
At 04:40 12/6/2003, you wrote:
>
>Thank you VERY much. :o)
>
>As for a second pair of eyes, I think I've just found a job for my
>not-too-technical friend who's been bugging me about finishing this project!
>=====================================================
>.______<-------------------\__
>/ _____<--------------------__|===
>||_ <-------------------/
>\__| Mr Trick
>
>
>>From: Derek Parnell <ddparnell at bigpond.com>
>>Reply-To: EUforum at topica.com
>>To: EUforum <EUforum at topica.com>
>>Subject: Re: Software Design Process
>>Date: Thu, 12 Jun 2003 17:26:37 +1000
>>
>>
>>On Thu, 12 Jun 2003 14:08:42 +1000, <mistertrik at hotmail.com> wrote:
>>
>>>
>>>I have been working on a fairly large software project, with database
>>>and display components, and the all-important user interface. Now my
>>>coding method is ad hoc at best, and I haven't used any particular
>>>system of design or coding.
>>>
>>>I managed to get the display component of this system fairly complete,
>>>and some of the user interface directly related to the display
>>>component, but when I started coding database and more advanced user
>>>interface stuff - in my ad hoc way - it all just ground to a halt.
>>>
>>>Now, I can see how it might benifit having some kind of perfunctory
>>>overall design and process to follow. Can anyone suggest ideas or
>>>resources for how I might go about doing this? This is a one-man
>>>project, so I don't imagine I would need something as complicated as
>>>ISO/IEC 12207 compliance...
>>>
>>>To the Euphoria heavyweights, how do you guys plan your projects?
>>
>>Firstly, how much I weigh is not for public information.
>>
>>Secondly, "ouch!" - I feel your pain.
>>
>>There is no easy way out - you have to work at it. Unless your system can
>>be totally specified on a single piece of A4 paper and be understood by a
>>8th grader, you should stop now, and put things into order.
>>
>>On the assumption you don't want to work on the same system forever
>>before its released, you need to know when to stop working on it. The
>>easiest way is to write a list the things that the system MUST be able to
>>do. Then stop working when the system can do all of them.
>>
>>This is the Requirements List. Most likely, a simple list will not
>>adequetely express, in an unambiguous manner, the full requirements. So,
>>for each item in your WRITTEN DOWN list (yes, writing it down is
>>important) you ought to add enough detail so that, hyperthetically,
>>somebody else could write your system for you. This is a balancing act,
>>for sure. It is easy to write too little detail as it is to write too
>>much. Remember to describe WHAT the system should deliver rather than HOW
>>it should deliver it.
>>
>>One useful technique for the UI aspect of your system, is to write down
>>the 'use cases'. That is, how a person will actually use the system to do
>>each single, very specific, thing. These are usually written as a set of
>>actor- action-effect statements. For example, if I'm describing how to
>>use IE to view a web page.
>>
>> Actor Action Effect
>>
>>Often you will have a pre-requirement specified too. In this example,
>>that might be that IE has been started running (this might be a link to
>>another use-case).
>>
>>A use-case will always have the primary process flow. It may also have
>>many alternate flows that are there to deal with exceptional
>>circumstances. In the example above, you might also have ...
>>
>>Exception after (4): Error message 'page not found'.
>>5. User Check the spelling of the URL and correct if needed.
>>
>>
>>When you have use-cases documented, testing the system becomes real easy.
>>Just follow the use-cases. Any unexpected effects might be bugs or
>>missing use-case material.
>>
>>
>>Don't build any production quality code until you have the requirements
>>specified. However, one of the better ways of understanding what the
>>requirements are is to build prototypes. Demo programs, or sample
>>programs, that help you play with your ideas until you fully understand
>>what you (or your clients) want. Never convert a prototype into a
>>production system. Always start a production system from a clean slate.
>>The prototype is a learning method where mistakes and dead-ends are
>>expected. You are allowed to
>>compromise quality in protypes. However, these don't convert well into
>>production code.
>>
<snip>
>
>
5. Re: Software Design Process
Hi Derek, you wrote:
> On Thu, 12 Jun 2003 14:08:42 +1000, <mistertrik at hotmail.com> wrote:
<snip>
>> To the Euphoria heavyweights, how do you guys plan your projects?
<snap>
> ---------------------------------
> Welcome to System Development 101.
> ---------------------------------
<snup>
Thank you very much for this informative lesson!
Best regards,
Juergen
--
/"\ ASCII ribbon campain | |\ _,,,---,,_
\ / against HTML in | /,`.-'`' -. ;-;;,_
X e-mail and news, | |,4- ) )-,_..;\ ( `'-'
/ \ and unneeded MIME | '---''(_/--' `-'\_)
6. Re: Software Design Process
On Thu, 12 Jun 2003 17:26:37 +1000, Derek Parnell
<ddparnell at bigpond.com> wrote:
>On Thu, 12 Jun 2003 14:08:42 +1000, <mistertrik at hotmail.com> wrote:
>
>> I have been working on a fairly large software project, with database =
and=20
<snip>
>> - in my ad hoc way - it all just ground to a halt.
Sounds familiar
=46irst off, I'll thank Derek for his post, most informative.
Anyone interested, a good read is:
http://www.joelonsoftware.com/navLinks/fog0000000247.html
(the painless functional specifications page)
I also liked the Martin Fowler interview at:
http://www.artima.com/intv/
>Secondly, "ouch!" - I feel your pain.
Glad to know we all occasionally(/often/usually) hit this ;->>
>There is no easy way out - you have to work at it.=20
How true
<oops, I've over snipped here: Something Derek said:>
I like: stop when done: way before you can do no more.
(Although Leonardo da Vinci carried the Mona Lisa everywhere he went
until his dying day, he also managed to do a lot of very good stuff he
actually finished).
When I feel stuck on a project, I return to the manual to write in the
most self-explanatory style I can imagine, how it will be used.
a) Take a break and write the easy stuff which needs to be written.
=46ill in the fluff which one day will have to be done anyway..
b) The bits giving grief: if you cannot write simple, obvious, common
sense explanations, the design is wrong. Not just wrong, but bad,
terrible, awful, and unacceptable. And you still want to code it?
c) When that fails, assume the user needs to know all the nitty
gritty, and replace eg "Press OK to accept the changes" with "When OK
is pressed the checksum will be validated, stored in table[5]
with..... *BUT* try to write it in a style the village idiot will get
I assume you already keep a simple list of outstanding items, and sort
them by priority. With a cutoff point for version 1.
>Don't build any production quality code until you have the requirements=20
>specified.
Spoilsport!
>Never convert a prototype into a production system.=20
ARGHH! Derek is quite right of course.
>Time to address System Architecture. Otherwise known as "how it all =
hangs=20
>together". Write down, usually with plenty of diagrams, the conceptual=20
>components of your system.
This I find the killer. Beyond a trivial case, I just can't do this :(
When I was much younger, people used to take the piss out of me
because I always said "I'll draw a diagram". It hurt and it stuck;
now it seems I have a mental block on this...
Pete
