Standard Design and Development Methodologies

[Arved Sandstrom]

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

 

[Martin Gregorie]

On 11/27/2011 4:34 AM, Arved Sandstrom wrote:
...

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.

 

[Arne Vajhøj]

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

 

[Arne Vajhøj]

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.

Arne

 

[Arved Sandstrom]

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

 

[Gene Wirchenko]

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.

Not necessarily. XML is not the only standard. It just has a
loud drummer.

Sincerely,

Gene Wirchenko

 

[Arne Vajhøj]

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?

Arne

 

[Arne Vajhøj]

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

 

[Gene Wirchenko]

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

 

[Arved Sandstrom]

On 12/3/2011 1:52 PM, Arved Sandstrom wrote:

[ SNIP ]

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