Where's the beef (UML design)?

  • Thread starter Paul H. Gusciora
  • Start date
P

Thread Starter

Paul H. Gusciora

Maybe I missed something in the archives, but I did not see a UML (Universal Modeling Language) design for the project on which people are
contributing code?

I think that a UML design would be critical to communicating and negotiating the layout of the basic design concepts (fixed array of structures vs. dynamically malloc'ed structures; one-to-one, many-to-one, and many-to-many relationships between various record types; use cases to
discover deficient operations; interfaces implemented by add-ins (I/O handlers) etc.)

Once there was a published UML design, the coding would proceed faster, no matter what the language used to express the design. We might all agree
that some portions of the project which do not have to be hard-real-time were better handled in an alternative language (Java, Perl, etc.). For
example, we often find that DCS (distributed control system) and APC (advanced process control) configuration is easiest done in spreadsheets which used the native formulas to exploit regularity in the tag configuration. The result is exported as a .CSV or tab-delimited .TXT files into a DCS/APC or PLC bulk configuration utility.

The UML design is also a major portion of what one would publish to document the internals.

Paul H. Gusciora
San Rafel, CA

Algorithms are free. What is expensive is interfaces to algorithms, and the
engineering interface to apply them.



_______________________________________________
LinuxPLC mailing list
[email protected]
http://linuxplc.org/mailman/listinfo/linuxplc
 
C

Curt Wuollet

"Paul H. Gusciora" wrote:

> Maybe I missed something in the archives, but I did not see a UML
> (Universal Modeling Language) design for the project on which people are
> contributing code?

No you didn't miss it.
The project almost died when trying to produce a detailed design ready to be coded. Due to human nature we were progressing towards half a dozen different designs. We still have at least
three, Phil's Java machine, Hugh's C++ OOP design and the incremental design process I have ongoing. Two of those were, I believe, more or less independant of this project. This approach
has, so far, seemed to work better for an all volunteer, open source project. I will go on with it as long as it works. If you were paying
people and could demand that they work together to produce a paper design first, I'm sure that the UML thing would work.

>
> I think that a UML design would be critical to communicating and
> negotiating the layout of the basic design concepts (fixed array of
> structures vs. dynamically malloc'ed structures; one-to-one, many-to-one,
> and many-to-many relationships between various record types; use cases to
> discover deficient operations; interfaces implemented by add-ins (I/O
> handlers) etc.)

I don't, in this situation. In another situation, perhaps. Maybe later on in this one.

>
> Once there was a published UML design, the coding would proceed faster, no
> matter what the language used to express the design. We might all agree
> that some portions of the project which do not have to be hard-real-time
> were better handled in an alternative language (Java, Perl, etc.).

We might not agree on anything ( I've seen that here) that makes that methodology invalid. I can't force people to arrive at a concensus.
Here we need a pull methodology rather than a push. We have recognized that the ancillaries can be done in alternate languages.

> For
> example, we often find that DCS (distributed control system) and APC
> (advanced process control) configuration is easiest done in spreadsheets
> which used the native formulas to exploit regularity in the tag
> configuration. The result is exported as a .CSV or tab-delimited .TXT files
> into a DCS/APC or PLC bulk configuration utility.
>

Could very well be.

>
> The UML design is also a major portion of what one would publish to
> document the internals.

Source code is the ultimate documentation.

I know you want to help, but, if we go back and try to achieve a consensus again on the process I think it will do more harm than good. We're moving
albeit slowly and bringing along the majority, I hope, of interested people.

Please don't be offended, hang around and if you feel like it, contribute. Please don't disrupt the fragile start, getting a team going is more
important than methodology right now. It's been much harder than the technological aspects.



_______________________________________________
LinuxPLC mailing list
[email protected]
http://linuxplc.org/mailman/listinfo/linuxplc
 
J

Jack Gallagher

Curt Wuollet Wrote
> Source code is the ultimate documentation.
>

This is the single largest problem with software. Too many people believe this to be true. I have remained quiet until this point on the progress that was made here, but I can no longer. I still believe a good design, even if not everyone agrees with it, is important before coding begins. Speaking for myself, I can tell you that I can't follow the thought process
of this system without design documentation. Code is NOT documentation. I am not trying to slow the progress made here. I am merely trying to state that I cannot help this process without a design. I also believe that just leaving code for people to read is not going to attract more people to work on this project. There still needs to be one document that at least explains the first cut of the system. Even if it is simplified. Refusal to write such a document is just admitting that one does not like to write
documentation.

Jack Gallagher
Lead Software Engineer
SESCO (a subsidiary of HARMON Industries)


_______________________________________________
LinuxPLC mailing list
[email protected]
http://linuxplc.org/mailman/listinfo/linuxplc
 
J
-> Refusal to
-> write such a document is just admitting that one does not
-> like to write
-> documentation.

Is this my cue?

I have been talking a bit with Jiri offline to work on his smm documentation. This should be ready to post in a day or two (once I get CVS working :^} )

Here is the rub..... I am not very fluent with C. I can sort of fake my way through bonehead C(tm), but more advanced concepts need some explaining.

I will go back through the list a bit (probably only as far as 'Round 2' when code started to appear) and try to reconstruct some of the agreed upon items and pull them together. It may take a few days, though, as I :


A. attempt to understand some of the concepts.
B. Start up a new production line at my day job (as if it was only during the day :^})

I will keep people posted as events warrant.

--Joe

_______________________________________________
LinuxPLC mailing list
[email protected]
http://linuxplc.org/mailman/listinfo/linuxplc
 
Hi Folks:

I have to agree strongly with Jack here. Source code should *never* be considered the documentation.

As a (possibly poor) example, consider the following: would anyone here ever attempt to take a road trip without knowing what the destination is? In other words, if I asked Curt to deliver instructions on how to drive from Saginaw Michigan to Grand Rapids Michigan, he probably could (and his instructions/source code) would probably be fairly accurate). However, if I
told him just to write the directions without telling him where to go, not only will he not know where he was going, but he also would not know when he got there (when to quit). The lesson from here: you need to know where you are
going so you know when you arrive! Documentating the software is the same, you need to know what your final objective is before you can claim that you arrived. Without documentation, you will never know even if you are heading in the right
direction.

Ron

_______________________________________________
LinuxPLC mailing list
[email protected]
http://linuxplc.org/mailman/listinfo/linuxplc
 
M
No you didn't miss anything. There is no UML design. In fact there isn't really any solid documented design. We're doing this in hacker mode -- code something up and try it.

(Well .. it _does_ work for some projects! <smile>)

If you look back into the archives you'll notice that there was an incredible flurry of different opinions early in the project. In my opinion this has definitely hindered any effort to produce a reference design.

I would enjoy seeing a UML reference design. But, if you (or anyone) produced one, they'd have to recognize that this project is staffed by a bunch of volunteers with different ideas. Quite possibly there would be submissions that didn't meet the design.

If you want to try and put something together, go for it!

Mark


_______________________________________________
LinuxPLC mailing list
[email protected]
http://linuxplc.org/mailman/listinfo/linuxplc
 
D
I generally agree with Curt in this: upfront group design has been tried in this project without success. This doesn't mean that design is worthless, but it may mean:

1. A one person design is more useful to get things *started*.
2. The best time for detailed design is after we've learned from the initial implementations. Yes, this is likely to lead to a reimplementation.

There's a very interesting (and somewhat scary) paper from the 4th Pattern Languages of Program Design conference about this that was discussed on
Slashdot recently: http://www.laputan.org/mud/mud.html. Basically, it deals with the question "if this design pattern is so horrible, why do people keep
doing it? why do they keep using the results?". One of their conclusions is that this sort of non-design may be inevitable at certain stages of a
project. Maybe we're in one of those stages now. They also deal with ways to get out of the ball of mud into something more livable later on. We'll probably need that advice too :)

Hoping that this descent into comp sci hasn't driving Curt catatonic :),

Dan Pierson


_______________________________________________
LinuxPLC mailing list
[email protected]
http://linuxplc.org/mailman/listinfo/linuxplc
 
S

Simon Martin

<lurk mode off>

Hi Ron, Jack, et al.

With respect the objectives that Ron addressed in his mail, I think there is a general consensus on the goals for this project, so I think I can say that we know where we are going.

With respect documentation as a subject in itself, there is a great difference between an open source project like this, and the usual in-house design. I am not depreciating the necessity or documentation, I would just like to point out the major differences.

When you do an in-house design you have a well defined group of people who are given objectives (that they may or may not like), a timescale (which they will not like) and a pay check.

When you do an open source, distributed development project you get a completely undefined, heterogeneous group of people, so that basic design can take years. People will take the parts of the project that they like (because of personal taste, knowledge, challenge, etc) and fix themselves a timescale. The satisfaction is something that works. Someone comes along picks up what's already done, looks at it, decides he/she can do better, and does (or fails at the attempt) and so version 2 is released, then
version 3, and ... ad infinitum.

Where does the design appear? The high level design is in the mission statement of the project. The generation of a low level design is next to impossible (ever tried to reach a conclusion in a brainstorming with 40 people which never stop???), and will cause frustration and desertion of those people who are interested in coding.

There is a very good article about this (I think I got the reference off of this list). It's called "The Cathedral and the Bazaar" and it's about how Open source projects work. This is the URL:
http://www.tuxedo.org/~esr/writings/cathedral-bazaar/cathedral-bazaar.html#toc1

<lurk mode on>

Debian GNU User
Simon Martin
Project Manager
Isys
mailto: [email protected]

Chaos reigns within.
Reflect, repent, and reboot.
Order shall return.

_______________________________________________
LinuxPLC mailing list
[email protected]
http://linuxplc.org/mailman/listinfo/linuxplc
 
C

Curt Wuollet

Hi Jack

Look at it this way. We are doing that design right now so it can be documented, coded, critiqued and discussed. The code we are putting up should be looked on as visual aids to understanding and communication of ideas. It may or may not end up on the final product. It is not unusual to do a pilot project to discover the issues and requirements of a major project.. That is my perspective on this. As we go through each section it focuses and directs the thinking much more effectively than the random undirected discussion that preceded it. At the end of the pilot we will have not only better insight into the issues and options, but also a tool that will
permit development and testing of I/O and a reference point for comparison. If you would like to be responsible for negotiating a software specification for the second pass, that position is open. From what I've seen, any spec would be a starting point for discussion not an enforcable contract with our developers. To that end, I'm using my idea about how to do a given section
as a start and listening to what is contributed. It's pull versus push. At this stage, code conveys ideas more effectively than discussion. And if no one submits better code, it's assumed we can move on. Jiri's looking at a
keyboard example for exercising his mm software and I am working on a simple I/O process example. In a couple of weeks we've made more progress
than since January. Most everyone has been kindly tolerant of my simple pilot because it's better to be moving on a simple pass than to be at a standstill trying to do too much. Besides, I'm a simpleton at heart :eek:).

Though this be madness, yet there is method to it ....

regards

cww

_______________________________________________
LinuxPLC mailing list
[email protected]
http://linuxplc.org/mailman/listinfo/linuxplc
 
R

Ralph G. McDonald

A design specification of some sort is important. On all of our projects we normally have an "Automation Spec" or " Sequence of Operations Spec" so we know where we are going and when we get there as Ron said. However we need to remember that in the experimental stages of a project too tight of a design specification may hinder innovation.

At this stage we need a general goal as furnished by Curt's concept, but there are many ways to code each component, ( logic engine, I/O,
communications, Memory Mapping, etc ). There may be multiple concepts of each for awhile, just as there are different ideas of the best programming language. As the project progresses the implementation that fits best should become apparent.

Speaking of memory mapping, I just finished reading the SMM Documentation that Joe Jansen did and it was very helpful to me in understanding the
functions and the memory maps. Good job Joe.

I would like to make the suggestion that anyone who is working on a component that they feel does not have a complete enough specification, write one for that component, post it, and carry on. Others will know what you are intending to do, and it may encourage others in this "herd of cats"
to do likewise.

To progress:

Ralph

_______________________________________________
LinuxPLC mailing list
[email protected]
http://linuxplc.org/mailman/listinfo/linuxplc
 
Hello,

Simon Martin:
> The generation of a low level design is next to impossible (ever tried to
> reach a conclusion in a brainstorming with 40 people which never stop???)

I believe the customary phrase is `herding cats'.

Jiri
--
Jiri Baum <[email protected]>
Windows is not popular. Windows is *widespread*. Linux is popular.

_______________________________________________
LinuxPLC mailing list
[email protected]
http://linuxplc.org/mailman/listinfo/linuxplc
 
Top