Path: utzoo!attcan!utgpu!jarvis.csri.toronto.edu!rutgers!tut.cis.ohio-state.edu!ucbvax!mtxinu!unisoft!hoptoad!hsfmsh!dumbcat!marc
From: marc@dumbcat.UUCP (Marco S Hyman)
Newsgroups: comp.object
Subject: Re: programming design methodologies fo
Summary: Design it twice with documentation
Message-ID: <116@dumbcat.UUCP>
Date: 28 Oct 89 19:50:32 GMT
References: <910@gorath.cs.utexas.edu> <135300011@p.cs.uiuc.edu> <14114@athertn.Atherton.COM>
Reply-To: marc@dumbcat.UUCP (Marco S Hyman)
Organization: MH Software, Hayward, Ca.
Lines: 47

In article <14114@athertn.Atherton.COM> jimb@athertn.UUCP (Jim Burke) writes:
    Without a concept of design
    early in system development, the people with the money have no way of
    estimating how much of their money will be required.

It's not a design that's used for estimating costs, it's a schedule.  And if
the schedule doesn't include the time to throw one design away, it's not
worth anything.  Why do you thing that software engineering and software
projects in general have such a bad reputation in some circles?  Non-trivial
projects are (almost) always late and over budget.  Why?  Because, IMHO,
most programmers are no good at saying NO.  They feel pressured to not
include the time for the second design in the original schedule and, when
the design problems crop up, feel pressured to somehow make it work. Too
many programmers give in to this pressure -- and therefore are placed in a
position where they are guaranteed to fail.

It's my hope that object-oriented programming will help by limiting the
amount of re-design needed in addition to class/object re-use.  Often the
re-design effort is on changing the data flow.  When this happens it may be
possible to keep many of the existing objects.

In article <4323@ncsuvax.ncsu.edu> jnh@ecemwl.ncsu.edu (Joseph N. Hall) replied:
    >The folks who resist formal design tend to be the same folks who tell you
    >that the best and only documentation required is the code.  IN other words,
    >hackers.  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    In those cases where the code is capable of being sufficient documentation,
    IT IS THE BEST DOCUMENTATION, when written properly.  It took me a long time
    to come to this conclusion, but the arguments are powerful and persuasive.

In any non-trivial piece of code the source code alone is NEVER enough.
(The only exception to this is when the source code is WEB or something like
it.)  The source code does not say *why* certain decisions were made and,
sometimes just as important, does not include a history of what didn't work.
This is important information.

Too often I've seen someone go in and ``clean up'' some code while fixing a
bug just to have it break someplace else.  All this because the original
programmer did not note *why* things were done the way they were. 
Unfortunately, programmers don't seem to learn the necessity of adding this
kind of documentation, preferably to the source, until they've been bitten
while cleaning up their own code many months after it was written. Some don't
even learn it then.

--marc
-- 
// Marco S. Hyman		{ames,pyramid,sun}!pacbell!dumbcat!marc