Groups > comp.lang.java.programmer > #10471

Re: Standard Design and Development Methodologies

From	Arved Sandstrom <asandstrom3minus1@eastlink.ca>
Newsgroups	comp.lang.java.programmer
Subject	Re: Standard Design and Development Methodologies
References	(5 earlier) <vFWyq.58884$rF5.53626@newsfe19.iad> <4ed05727$0$289$14726298@news.sunsite.dk> <avh3d7h90306idj3v7qedci95d1tvi0ds4@4ax.com> <j7qAq.12566$Uq2.9347@newsfe05.iad> <4ed98e08$0$286$14726298@news.sunsite.dk>
Message-ID	<heuCq.4986$X02.724@newsfe03.iad> (permalink)
Organization	Public Usenet Newsgroup Access
Date	2011-12-03 14:52 -0400

Show all headers | View raw

On 11-12-02 10:48 PM, Arne Vajhøj wrote:
> On 11/27/2011 7:34 AM, Arved Sandstrom wrote:
>> On 11-11-27 01:18 AM, Gene Wirchenko wrote:
>>> On Fri, 25 Nov 2011 22:04:04 -0500, Arne Vajhøj<arne@vajhoej.dk>
>>> wrote:
>>>> On 11/22/2011 6:57 PM, Arved Sandstrom wrote:
>>>>> Most of the diagrams I draw, I and a few others _are_ the intended
>>>>> audience. We're just brainstorming on whiteboard or paper.
>>>>
>>>> The guys that will maintain the code in 10 years may appreciate
>>>> it if they get a copy of some of that stuff that explains why
>>>> certain code was designed in a certain way.
>>>
>>>       I put comments like that in my code.
>>
>> Me also. In my experience requirements documents and design documents
>> are on borrowed time as soon as their related implementation goes into
>> production. Depending on the organization you may actually be able to
>> find them for a year or two, but nobody will be updating them to reflect
>> maintenance work. And 5 or 10 years after go-live your odds of finding
>> *any* original requirements or design docs are not good, regardless of
>> whether you use a version control system or an ECMS to initially store
>> them.
>>
>> The only thing that stays with the code - reliably - *is* the code,
>> including comments.
> 
> Nothing prevents you from checking the docs into the same source
> control as the code.
> 
> Arne
> 
No, nothing prevents that. I could swear I mentioned version control myself.

That's not the point. The point is, let's say someone checks in that
Microsoft Word 2007 binary into your source control. They prepared the
UML diagrams with some tool that nobody else has, but that's irrelevant,
because they exported into PNG from the tool, and the Word doc only
includes the PNG images.

So any maintenance programmer down the road, who actually cares enough
to think about updating that design doc, already will not touch the
diagrams. Furthermore, he might have something other than Word, or a
different version of Word, or maybe when the doc was checked in it was
actually an exported PDF, and nobody's got full Acrobat. Maybe the
maintenance coder doesn't update and annotate properly to make his
changes clear...and since the document is binary the version control
system is *precisely useless* for telling you what the changes were.

Use an XML documentation format, you say. Well, this becomes a chicken
and egg thing then. Any development organization mature enough to be
using DocBook or DITA or some other XML to author external documentation
is already mature enough to fall into the top 10% of organizations for
whom this entire discussion is a moot point.

Fact is, and this has been my experience, diagrams serve a purpose up
until product release. After that the code, with code comments, is the
authoritative (and only reliable) source of information.

AHS

Thread

Standard Design and Development Methodologies Novice <novice@example..com> - 2011-11-19 19:42 +0000
  Re: Standard Design and Development Methodologies Arne Vajhøj <arne@vajhoej.dk> - 2011-11-19 21:22 -0500
    Re: Standard Design and Development Methodologies Novice <novice@example..com> - 2011-11-20 16:55 +0000
      Re: Standard Design and Development Methodologies "Charles Hottel" <chottel@earthlink.net> - 2011-11-20 22:20 -0500
  Re: Standard Design and Development Methodologies Arved Sandstrom <asandstrom3minus1@eastlink.ca> - 2011-11-19 23:01 -0400
    Re: Standard Design and Development Methodologies Lew <lewbloch@gmail.com> - 2011-11-19 20:13 -0800
      Re: Standard Design and Development Methodologies Lew <lewbloch@gmail.com> - 2011-11-19 20:16 -0800
      Re: Standard Design and Development Methodologies "Derek K. Wodenhouse" <dkw@none.of.your.biz> - 2011-11-19 23:49 -0500
        Re: Standard Design and Development Methodologies Lew <lewbloch@gmail.com> - 2011-11-19 23:45 -0800
          Re: Standard Design and Development Methodologies "Derek K. Wodenhouse" <dkw@none.of.your.biz> - 2011-11-20 03:49 -0500
            Re: Standard Design and Development Methodologies Robert Klemme <shortcutter@googlemail.com> - 2011-11-20 13:58 +0100
            Re: Standard Design and Development Methodologies Lew <lewbloch@gmail.com> - 2011-11-20 08:32 -0800
              Re: Standard Design and Development Methodologies "Derek K. Wodenhouse" <dkw@none.of.your.biz> - 2011-11-20 18:24 -0500
        Re: Standard Design and Development Methodologies Patricia Shanahan <pats@acm.org> - 2011-11-20 03:27 -0800
          Re: Standard Design and Development Methodologies spk <jhic@speak.invalid> - 2011-11-20 09:54 -0400
            Re: Standard Design and Development Methodologies Lew <lewbloch@gmail.com> - 2011-11-20 08:33 -0800
            Re: Standard Design and Development Methodologies thoolen <th00len@th0lenbot.thorium> - 2011-11-20 18:30 -0500
      Re: Standard Design and Development Methodologies Arved Sandstrom <asandstrom3minus1@eastlink.ca> - 2011-11-20 09:35 -0400
      Re: Standard Design and Development Methodologies Novice <novice@example..com> - 2011-11-20 17:18 +0000
        Re: Standard Design and Development Methodologies Lew <lewbloch@gmail.com> - 2011-11-20 10:30 -0800
          Re: Standard Design and Development Methodologies Arved Sandstrom <asandstrom3minus1@eastlink.ca> - 2011-11-21 07:23 -0400
      Re: Standard Design and Development Methodologies Arne Vajhøj <arne@vajhoej.dk> - 2011-11-25 21:51 -0500
        Re: Standard Design and Development Methodologies Lew <lewbloch@gmail.com> - 2011-11-25 20:07 -0800
    Re: Standard Design and Development Methodologies Novice <novice@example..com> - 2011-11-20 17:08 +0000
      Re: Standard Design and Development Methodologies Arne Vajhøj <arne@vajhoej.dk> - 2011-11-20 12:18 -0500
      Re: Standard Design and Development Methodologies markspace <-@.> - 2011-11-20 10:29 -0800
      Re: Standard Design and Development Methodologies Lew <lewbloch@gmail.com> - 2011-11-20 10:55 -0800
        Re: Standard Design and Development Methodologies Arne Vajhøj <arne@vajhoej.dk> - 2011-11-20 14:07 -0500
          Re: Standard Design and Development Methodologies Lew <lewbloch@gmail.com> - 2011-11-20 11:50 -0800
      Re: Standard Design and Development Methodologies Arved Sandstrom <asandstrom3minus1@eastlink.ca> - 2011-11-21 07:19 -0400
  Re: Standard Design and Development Methodologies Roedy Green <see_website@mindprod.com.invalid> - 2011-11-20 22:27 -0800
    Re: Standard Design and Development Methodologies Arved Sandstrom <asandstrom3minus1@eastlink.ca> - 2011-11-21 07:02 -0400
      Re: Standard Design and Development Methodologies Robert Klemme <shortcutter@googlemail.com> - 2011-11-22 18:52 +0100
        Re: Standard Design and Development Methodologies markspace <-@.> - 2011-11-22 11:37 -0800
          Re: Standard Design and Development Methodologies Gene Wirchenko <genew@ocis.net> - 2011-11-22 14:27 -0800
            Re: Standard Design and Development Methodologies Arne Vajhøj <arne@vajhoej.dk> - 2011-11-25 22:06 -0500
              Re: Standard Design and Development Methodologies Gene Wirchenko <genew@ocis.net> - 2011-11-26 21:16 -0800
                Re: Standard Design and Development Methodologies Arne Vajhøj <arne@vajhoej.dk> - 2011-12-02 21:53 -0500
                Re: Standard Design and Development Methodologies Gene Wirchenko <genew@ocis.net> - 2011-12-04 21:25 -0800
                Re: Standard Design and Development Methodologies Arne Vajhøj <arne@vajhoej.dk> - 2011-12-05 22:41 -0500
                Re: Standard Design and Development Methodologies Gene Wirchenko <genew@ocis.net> - 2011-12-05 19:58 -0800
          Re: Standard Design and Development Methodologies Arved Sandstrom <asandstrom3minus1@eastlink.ca> - 2011-11-22 19:57 -0400
            Re: Standard Design and Development Methodologies Arne Vajhøj <arne@vajhoej.dk> - 2011-11-25 22:04 -0500
              Re: Standard Design and Development Methodologies Gene Wirchenko <genew@ocis.net> - 2011-11-26 21:18 -0800
                Re: Standard Design and Development Methodologies Arved Sandstrom <asandstrom3minus1@eastlink.ca> - 2011-11-27 08:34 -0400
                Re: Standard Design and Development Methodologies Patricia Shanahan <pats@acm.org> - 2011-11-27 08:39 -0800
                Re: Standard Design and Development Methodologies Martin Gregorie <martin@address-in-sig.invalid> - 2011-11-27 20:07 +0000
                Re: Standard Design and Development Methodologies Arne Vajhøj <arne@vajhoej.dk> - 2011-12-02 21:48 -0500
                Re: Standard Design and Development Methodologies Arved Sandstrom <asandstrom3minus1@eastlink.ca> - 2011-12-03 14:52 -0400
                Re: Standard Design and Development Methodologies Arne Vajhøj <arne@vajhoej.dk> - 2011-12-05 22:50 -0500
                Re: Standard Design and Development Methodologies Arved Sandstrom <asandstrom3minus1@eastlink.ca> - 2011-12-06 07:21 -0400
      Re: Standard Design and Development Methodologies Arne Vajhøj <arne@vajhoej.dk> - 2011-11-25 21:54 -0500
    Re: Standard Design and Development Methodologies Arne Vajhøj <arne@vajhoej.dk> - 2011-11-25 21:47 -0500

csiph-web