Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.java.programmer > #10069 > unrolled thread

Standard Design and Development Methodologies

Back to article view | Back to comp.lang.java.programmer

Contents

  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

Page 3 of 3 — ← Prev page 1 2 [3]

#10545

On Mon, 05 Dec 2011 22:41:39 -0500, Arne Vajhøj <arne@vajhoej.dk>
wrote:

>On 12/5/2011 12:25 AM, Gene Wirchenko wrote:
>> On Fri, 02 Dec 2011 21:53:05 -0500, Arne Vajhøj<arne@vajhoej.dk>
>> wrote:
>>> On 11/27/2011 12:16 AM, Gene Wirchenko wrote:
>>
>> [snip]
>>
>>>>        I believe in standards, but UML is awkward to enter.  Sketches
>>>> are much faster, and I can think with them.  I understand about
>>>> documenting, but UML is just too fiddly for my taste.
>>>
>>> You may think your sketch is very readable, but other people
>>> reading it will get the same info as you from it, because the
>>                  ^
>>> semantics of things shown are not standardized.
>>
>>       I think you are missing a "not" at the indicated position.  I am
>> assuming that in my response.
>
>Yes.
>
>>       Not necessarily.
>
>So what notation with standardized semantics are you using
>
> >                         XML is not the only standard.  It just has a
> > loud drummer.
>
>????
>
>What does XML have to do with the topic?

     Oops.  UML.  I do not care for either, but usually, I am more
careful about my "enemies".

Sincerely,

Gene Wirchenko

[toc] | [prev] | [next] | [standalone]

#10180

On 11-11-22 03:37 PM, markspace wrote:
> On 11/22/2011 9:52 AM, Robert Klemme wrote:
> 
>> On 21.11.2011 12:02, Arved Sandstrom wrote:
>>> I'm convinced of the utility of a specific number of UML diagrams, when
>>> used with pencil and paper or on whiteboards. There are only 2 or 3 of
>>> the diagrams I would ever use in technical documentation, and then very
>>> sparingly. For the latter I make a point of not using any "UML editors";
>>> rather, I use my favourite drawing program with UML stencils.
> 
> 
> I'd think that if a diagram, UML or otherwise, is useful on a
> whiteboard, then the same diagram would be useful in the requirements
> document, as it explains to still yet more folks what is intened.
> 
[ SNIP ]

I won't tell anyone what diagrams to put in what documents. I just hope
that the diagrams they choose to include are necessary and useful.

Almost every requirements document I see has a plethora of diagrams, UML
or otherwise. Pretty much all of them could be usefully gotten rid of. I
like seeing lists or tables of carefully written requirements in a
requirements document.

Design docs are the ones that sometimes benefit from some carefully
chosen diagrams, and that's where I sometimes include a few. Again, very
sparingly - pretty much all the design docs I see could lose 50-90
percent of their diagrams and be better for it. I've seen some very good
design docs that were all text.

Most of the diagrams I draw, I and a few others _are_ the intended
audience. We're just brainstorming on whiteboard or paper.

AHS

[toc] | [prev] | [next] | [standalone]

#10256

On 11/22/2011 6:57 PM, Arved Sandstrom wrote:
> Almost every requirements document I see has a plethora of diagrams, UML
> or otherwise. Pretty much all of them could be usefully gotten rid of. I
> like seeing lists or tables of carefully written requirements in a
> requirements document.

Text is certainly necessary in requirement documentation.

Numbering is practically necessary to be able to easily refer
as part of tracking.

But I can certainly see cases where:
- use case diagrams are useful to show relation ships between use
   cases (this obviously only applies if uses cases are used for
   requirments)
- activity diagrams to describe complex flows precisely
- deployment diagrams to show the context where the software
   will be used
are useful.

> Design docs are the ones that sometimes benefit from some carefully
> chosen diagrams, and that's where I sometimes include a few. Again, very
> sparingly - pretty much all the design docs I see could lose 50-90
> percent of their diagrams and be better for it. I've seen some very good
> design docs that were all text.
>
> 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.

Arne

[toc] | [prev] | [next] | [standalone]

#10274

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:

[snip]

>> 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.

Sincerely,

Gene Wirchenko

[toc] | [prev] | [next] | [standalone]

#10277

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:
> 
> [snip]
> 
>>> 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.
> 
> Sincerely,
> 
> Gene Wirchenko

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.

AHS

[toc] | [prev] | [next] | [standalone]

#10279

On 11/27/2011 4:34 AM, Arved Sandstrom wrote:
...
> The only thing that stays with the code - reliably - *is* the code,
> including comments.

This is one of the reasons I love Javadoc, and similar systems. A
comment block right next to the thing it describes stays with the code,
and is more likely to get updated during maintenance than any other form
of documentation.

Patricia

[toc] | [prev] | [next] | [standalone]

#10280

On Sun, 27 Nov 2011 08:39:55 -0800, Patricia Shanahan wrote:

> On 11/27/2011 4:34 AM, Arved Sandstrom wrote:
> ...
>> The only thing that stays with the code - reliably - *is* the code,
>> including comments.
> 
> This is one of the reasons I love Javadoc, and similar systems. A
> comment block right next to the thing it describes stays with the code,
> and is more likely to get updated during maintenance than any other form
> of documentation.
> 
I agree completely.

At the other end of that scale, back in the early '80s I was contracting 
in a large mainframe shop. Their systems analysis and design group had a 
policy of actively destroying documentation as soon as their involvement 
was finished, regardless of how big or small their input to the project 
or change request had been.


-- 
martin@   | Martin Gregorie
gregorie. | Essex, UK
org       |

[toc] | [prev] | [next] | [standalone]

#10454

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

[toc] | [prev] | [next] | [standalone]

#10471

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

[toc] | [prev] | [next] | [standalone]

#10544

On 12/3/2011 1:52 PM, Arved Sandstrom wrote:
> 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.
>
> No, nothing prevents that. I could swear I mentioned version control myself.

You did.

> 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.

It does not happen that frequently that companies change word
processors.

It does happen occasionally.

But if the old one was reasonable mainstream, then the new
one can most likely convert docs from the old format to the
new format.

Even docs that are unmodifiable can provide information
for creating new docs.

> 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.

The code is obviously the authoritative source for what the
code does.

And the details in the code will certainly change and the
docs may end up not being kept uptodate.

But the more high level design changes less frequently and
even with some changes understanding how the app was
envisioned when it was created can be very useful.

Arne

[toc] | [prev] | [next] | [standalone]

#10552

On 11-12-05 11:50 PM, Arne Vajhøj wrote:
> On 12/3/2011 1:52 PM, Arved Sandstrom wrote:
[ SNIP ]

>> 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.
> 
> The code is obviously the authoritative source for what the
> code does.
> 
> And the details in the code will certainly change and the
> docs may end up not being kept uptodate.
> 
> But the more high level design changes less frequently and
> even with some changes understanding how the app was
> envisioned when it was created can be very useful.
> 
> Arne

On that note, the documentation that I most like to see, well after the
fact, is requirements (business and technical). Well-written test plans
and test cases, at the functional and higher levels, are also in this
ballpark.

Actually, the documentation that I really most like to see - the Holy
Grail - is business rules prepared by competent BAs. Pretty much the
input for the business requirements. But that's so rare that I am
leaving it out of the discussion after.

If called in to do new work - and significant maintenance work is also
more new work than anything else - I prefer requirements (technical
requirements that accurately and provably trace to business
requirements) first, existing code (with code comments) second, design
docs last.

My thinking along these lines is that signed-off requirements trump
everything else. You can take 'em to the bank. If a preceding team
botched the design and implementation it doesn't matter, the
requirements tell you where you want to be regardless.

If you do *not* have requirements, then existing code is next best,
because it is the "as-is", and it - rather than the design - defines the
requirements. Business will have come to think of the way that the
current system behaves as the requirements in any case, because they've
got nothing else. I've seen this a myriad of times.

Design docs are helpful usually only when they accompany good
requirements docs, accurately trace back to the requirements, *and* the
codebase is a faithful implementation of them. Otherwise they are fairly
useless. And even in the best circumstances they are not that helpful,
in my experience: a few nuggets here and there maybe, but 90 percent
bumf and handwaving.

AHS

[toc] | [prev] | [next] | [standalone]

#10255

On 11/21/2011 6:02 AM, Arved Sandstrom wrote:
> I'm convinced of the utility of a specific number of UML diagrams, when
> used with pencil and paper or on whiteboards. There are only 2 or 3 of
> the diagrams I would ever use in technical documentation, and then very
> sparingly. For the latter I make a point of not using any "UML editors";
> rather, I use my favourite drawing program with UML stencils.
>
> Diagrams have considerable merit to display information, and you may as
> well use a standardized notation. UML is OK for that. But if you find
> yourself struggling with the details of the notation, or the UML editor
> is getting in your way, you're wasting your time.

Just don't save time at the expense of the maintenance programmers
having to spend more time figuring out what the non-standard UML syntax
means.

Arne

[toc] | [prev] | [next] | [standalone]

#10253

On 11/21/2011 1:27 AM, Roedy Green wrote:
> Design patterns are the most important.  I have yet to be convinced of
> the utility of tools like UML.

Since UML is not a tool but a standard for how tools visual represent
things, then that does not say much.

Arne

[toc] | [prev] | [standalone]

Page 3 of 3 — ← Prev page 1 2 [3]

Back to top | Article view | comp.lang.java.programmer

csiph-web