«

On Fri, 20 Jul 2012 13:39:20 +0200, Robert Klemme wrote:

> And btw., roundtrip tools don't help much with updating diagrams which
> are sitting in text documents. That still has to be done manually -
> unless someone invents a system which manages everything (code and
> documentation). But then it would still need a human being to decide
> whether a new sub class should show up on a particular diagram or not.
>
I've only ever seen one that did. It came out of a UK University but
never seems to have come to anything. Its 'presentation face' mixed
textual documentation and code fragments in a similar fashion to K&R or
(better) Kernighan & Pike, while still keeping the ability to maintain
the text without interfering with the code and to develop and compile the
code without screwing up the overall look and feel of the 'presentation
face'. I can't remember how it dealt with diagrammatic material. I
thought it had a lot of promise though it was probably not a much higher-
level tool that Javadocs.

My main objection to all theses methodologies is that the documentation
is usually stored and maintained separately from the code, which to me
means that it isn't going to be maintained. As I've said before, the big
advantage, as I see it, of Javadocs is that at least there's a good
chance that module-level documentation will be maintained as the code
gets modified.

Its a pity there isn't anything similar for a system's higher level
documentation like, for instance a combination source repository and data
dictionary, but the nearest I've seen to a decent attempt at that was the
long-defunct ICL Advanced Data Dictionary with its four quadrant
structure, version control and linkages between the quadrants:

processes | entities
data and | attributes
control flow | relationships
---------------------------------------
programs | schemas
pipelines | storage schemas
process management | tables

This could generate project documentation and code (both DDS and program
source) and manage version control across an entire system.


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

Martin Gregorie <> writes:
>My main objection to all theses methodologies is that the documentation
>is usually stored and maintained separately from the code, which to me
>means that it isn't going to be maintained.

IIRC, Doxygen generates docs from the source code and has an
extension or an option that will also generate some UML diagrams
from the source code.

And then, what answer would a /professional/ give to the question
»Do you use UML?«? I think a /professional/ answer would be:
»Whenever I am paid (sufficiently) to do this.«

On 20.07.2012 21:38, Stefan Ram wrote:
> Martin Gregorie <> writes:
>> My main objection to all theses methodologies is that the documentation
>> is usually stored and maintained separately from the code, which to me
>> means that it isn't going to be maintained.
>
> IIRC, Doxygen generates docs from the source code and has an
> extension or an option that will also generate some UML diagrams
> from the source code.

It has the same limitation as any other tool which generates diagrams
from source code: it cannot automatically add information needed for
proper diagram placement etc. The point is that laying out a diagram is
a creative task and diagrams are not just another representation of the
code. A properly crafted diagram adds information to what is present in
the code.

> And then, what answer would a /professional/ give to the question
> »Do you use UML?«? I think a /professional/ answer would be:
> »Whenever I am paid (sufficiently) to do this.«

That does not sound like an answer of a software development
professional - it reminds me more of a professional contract killer.
You make it sound like doing UML diagrams was something tedious or
distasteful which needs additional payment for compensation. ("We're a
code shop only. If you need diagrams that'll cost you extra bucks.")
Rather the needs of the task at hand should dictate whether a diagram is
in order or not.

Cheers

robert


--
remember.guy do |as, often| as.you_can - without end
http://blog.rubybestpractices.com/

On Fri, 20 Jul 2012 15:22:52 -0700, Patricia Shanahan wrote:

> On 7/20/2012 3:02 PM, Robert Klemme wrote:
>> On 20.07.2012 21:38, Stefan Ram wrote:
>>> Martin Gregorie <> writes:
>>>> My main objection to all theses methodologies is that the
>>>> documentation is usually stored and maintained separately from the
>>>> code, which to me means that it isn't going to be maintained.
>>>
>>> IIRC, Doxygen generates docs from the source code and has an
>>> extension or an option that will also generate some UML diagrams
>>> from the source code.
>>
>> It has the same limitation as any other tool which generates diagrams
>> from source code: it cannot automatically add information needed for
>> proper diagram placement etc. The point is that laying out a diagram
>> is a creative task and diagrams are not just another representation of
>> the code. A properly crafted diagram adds information to what is
>> present in the code.
>
> If anything, it is more important to remove information. A diagram with
> a box for each tree is not a good way of communicating the structure of
> a forest.
>

+1




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

On 7/20/2012 2:29 AM, Roedy Green wrote:
> On Thu, 19 Jul 2012 17:41:46 -0500, Leif Roar Moldskred
> <> wrote, quoted or indirectly quoted someone who
> said :
>> When it helps you to think and reason about the system you're developing
>> and when it helps to communicate information about the system to other
>> people working on it.
>
> I think the biggest problem comes with keeping it up to date. This is
> extra work, but without it the diagrams are worse than useless.

With the level of detail most often used in UML diagrams, they
should not need to be updated so often.

Arne

On 7/20/2012 7:39 AM, Robert Klemme wrote:
> On 20.07.2012 09:16, Fredrik Jonson wrote:
>> In <> Roedy Green wrote:
>>> I think the biggest problem [of UML] comes with keeping it up
>>> to date.
>>
>> The more expensive UML tools have round trip engineering which makes
>> keeping it up to date with code less of a hassle. My limited experience
>> with round trip engineering is that has its own weakness; it picks up all
>> minor parts of the code too, including things that are not necessarily is
>> important to get the main picture of the design.
>
> Graphical programming (what these round trip tools promise to be able to
> do) does not work. The mere fact that you need to have every part of
> the code in the diagram leads to diagram overload. One of the important
> tasks when creating diagrams (not only UML) is to select what needs to
> be shown and how it needs to be shown. This is something a human needs
> to do. It cannot be automated. Normally to understand a system only a
> few classes need to be depicted and not with every detail (method, data
> member etc.). Updating diagrams with every changed detail is tedious
> and useless because it does not improve understanding. Often the basic
> relationships between classes remain the same because they are at the
> heart of the design.

Completely agree.

> My preferred tool is Visio with the free available set of UML stencils.
> This makes creating UML diagrams easy (because all the elements are
> there) but retains enough flexibility to mix in other information as
> needed.

I think ArgoUML is pretty nice.

I has some generation and reverse generation capabilities but I consider
those more as one time tools than the real round trip tool.

>> Myself, I mostly use class diagrams and sequence diagrams to introduce a
>> design to other developers. In most cases the diagrams never go further
>> than a whiteboard. When I have to, I use Umlet to persist them too.
>
> I use these diagram types in decreasing (estimated) frequency:
> - class
> - activity
> - state
> - sequence
>
> rarely:
> - object
> - deployment

For me: class, sequence, deployment, activity, use case.

Arne

On 7/20/2012 6:22 PM, Patricia Shanahan wrote:
> If anything, it is more important to remove information. A diagram with
> a box for each tree is not a good way of communicating the structure of
> a forest.

Yes.

Someone smart once said that insight is not about collecting
information but about throwing away information.

Arne

On 07/21/2012 12:22 AM, Patricia Shanahan wrote:
> On 7/20/2012 3:02 PM, Robert Klemme wrote:
>> On 20.07.2012 21:38, Stefan Ram wrote:
>>> Martin Gregorie <> writes:
>>>> My main objection to all theses methodologies is that the documentation
>>>> is usually stored and maintained separately from the code, which to me
>>>> means that it isn't going to be maintained.
>>>
>>> IIRC, Doxygen generates docs from the source code and has an
>>> extension or an option that will also generate some UML diagrams
>>> from the source code.
>>
>> It has the same limitation as any other tool which generates diagrams
>> from source code: it cannot automatically add information needed for
>> proper diagram placement etc. The point is that laying out a diagram is
>> a creative task and diagrams are not just another representation of the
>> code. A properly crafted diagram adds information to what is present in
>> the code.
>
> If anything, it is more important to remove information. A diagram with
> a box for each tree is not a good way of communicating the structure of
> a forest.

Right. It's both: adding and removing, but the point remains the same:
this is a task which cannot be automated.

Kind regards

robert

On 21.07.2012 19:16, Wanja Gayk wrote:
> In article <>,
> says...
>
>> Graphical programming (what these round trip tools promise to be able
>> to do) does not work. The mere fact that you need to have every part
>> of the code in the diagram leads to diagram overload.
>
> I have professionally worked with a framework that tries to do this, so
> I've got a bit experience in that. It works remarkably well.

I'd love to learn the name of the tool you used.

> What we were doing, when we were using the tool, was to model the
> database entities in detail as class diagrams, but for the activity
> diagrams we had to keep as much technical detail out of the diagrams as
> possible and abstract a lot.

What does that mean? Are your activity diagrams disconnected from the
Java code?

> We described the broad business decisions
> only and coded the detail like you've been doing it all the time: In
> plain old Java. For conditionals, the framework generated a hook method
> from the diagram, which we filled with life. For each activity a view
> was generated by the framework, which we could customize using a UI-
> designer and Java.

Do you mean view as in MVC? What kind of application are we talking
about here?

> It's very convenient, as long as you don't try to squeeze everything
> into one diagram.

Obviously.

> The only drawback is that you're virtually always
> short of screen estate.



>> And btw., roundtrip tools don't help much with updating diagrams which
>> are sitting in text documents.
>
> We've not put the diagrams onto paper. All we modelled and talked about
> was stored in model-files that the system held in sync with the
> software.

I wasn't specifically talking about paper. Did you include diagrams in
text documents (design documents) which explained the rationale of the
design in a more reader friendly way? If yes, how did you deal with
updating diagrams? If not, how did you convey the essence of the design
to other people (new team members etc.)?

Kind regards

robert


--
remember.guy do |as, often| as.you_can - without end
http://blog.rubybestpractices.com/

On Sat, 21 Jul 2012 00:02:08 +0200, Robert Klemme
<> wrote:

[snip]

>> And then, what answer would a /professional/ give to the question
>> »Do you use UML?«? I think a /professional/ answer would be:
>> »Whenever I am paid (sufficiently) to do this.«
>
>That does not sound like an answer of a software development
>professional - it reminds me more of a professional contract killer.
>You make it sound like doing UML diagrams was something tedious or
>distasteful which needs additional payment for compensation. ("We're a
>code shop only. If you need diagrams that'll cost you extra bucks.")
>Rather the needs of the task at hand should dictate whether a diagram is
>in order or not.

I have not found formal diagramming to be very useful. I had to
document using UML diagrams in some of my uni courses. I generally
did them *after* I wrote the code. Creating them required a bunch of
fiddling to make them come out clear. They were a time sink and did
not add anything to my understanding of the system.

OTOH, in-line code documentation I wrote as I coded. That stuff
was useful.

User documentation was stright-forward typing. I did that after
coding using bits of code as needed.

I can understand someone not wanting to do things that do not
help do the job. Avoid needless work.

Sincerely,

Gene Wirchenko