Re: Standard Design and Development Methodologies
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