-Ralf
--
You received this message because you are subscribed to the Google Groups "software_craftsmanship" group.
To post to this group, send email to software_cr...@googlegroups.com.
To unsubscribe from this group, send email to software_craftsma...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/software_craftsmanship?hl=en.
However your concern is interesting. How do you communicate design in a formalised way?
Cheers
Andreas
If you are doing it right, there will be a place where you can find your high level overview, for example in the IoC container config, or in the main method, of course that is no standard and it depends on the type of product, ecosystem, software design paradigm etc.
But I have a feeling you want to suggest something even better.
> I sure have my point of view ;-) But I�d like to hear how the
> craftsmen community is doing it. How do they bring new people on the
> team up to speed.
> Is it like "Welcome, Joe, here�s 30.000 lines of code for you. Just
> prowl through them and you�ll know how this baby works. Just start
> with the tests, whip up the debugger and off you go."
What if ...
We know how to write code that expresses its design better than
30,000 lines of code?
We work with the person to explain to them what is going on?
Ron Jeffries
www.XProgramming.com
For best results, avoid doing stupid things. -- Clifford Stoll (Acme Klein Bottle)
> As the Evans book points out, when you have a complex project, it's helpful
> to have a bit of documentation that helps someone get started. Not too much
> detail so the docs don't age so quickly, but at least a basic roadmap to see
> how things fit together. Without that, it'd be very tough to just look at
> the code of even a very clearly defined domain model and grok it, at least
> on a non-trivial project.
I'd like to have a diagram or something, sure. On the other hand it
is fun to see what ideas about design we /cannot/ express directly
in code ... if any.
Ron Jeffries
www.XProgramming.com
He who will not apply new remedies must expect old evils. -- Francis Bacon
I try to balance the need for a high level view with the code.
Anything in between is best communicated at a white board and erased
as soon as the meeting is over. 10,000 foot level design documents
tend to diverge less quickly. I would even assert that the more
abstract the design document, the slower it will diverge, but when you
get to a high enough level of abstraction, you have less of a design
document and more of what you might call a metaphor. Hmm, that sounds
familiar somehow :)
In an XP shop the communication of the design is going to be done with
the new programmer sitting down side by side with experienced
programmers and learning the design that way. I can not honestly think
of a better way to communicate the design of a system than sitting
side by side with another developer and actually working on the
system.
--
Curtis Cooley
curtis...@gmail.com
blog:http://ponderingobjectorienteddesign.blogspot.com
===============
Leadership is a potent combination of strategy and character. But if
you must be without one, be without the strategy.
-- H. Norman Schwarzkopf
--
Non-executable is the key, in my opinion. A suite of documenting
Cucumber tests is not "formal" because they can be executed and will
fail when the documents stray from reality.
If you can afford to pay an engineer to maintain a set of UML diagrams
full time to keep then in tune with reality, then I say why not? We
can argue that it's muda til the cows come home, but if you find it
valuable enough to engage a development resource full time in a non
development task, why not do it? And believe me, keeping a full set of
documents in touch with the reality of 250,000 lines of code, hehe now
LOC helps my argument, will be a full time job for at least one
development resource.
Craftsmanship, Agile, Lean etc.. tend to not want to engage an
engineer full time, and have found that working software is better
than comprehensive documentation and individuals and interactions are
better than tools and processes.
> I guess we as an industry we should be very clear about this. Because
> if not, the attribute "formal" is left to personal feelings and
> becomes very subjective. Which in turn can lead to using it as a means
> of power over: "You don´t share my feeling about this documentation
> being formal? Well, then you´re stupid and I´m a better programmer
> than you are. You better listen to me."
>
>
>>
>> I try to balance the need for a high level view with the code.
>> Anything in between is best communicated at a white board and erased
>> as soon as the meeting is over.
>
> That essentially means, the design is just in the heads of developers
> (in some abstract form, of course) - and somehow encoded in source
> code.
> The abstract form always has to be reproduced from the top of your
> head - or reverse engineered from code.
> Correct?
>
Well, if you want the high level design to be as close to reality as
you want, then yes, it's best kept in the heads of the developers and
in the source code. You seem to not care that once you write it down
in a non executable way, that it begins to diverge from reality. Are
you saying it's better to have written models that are easier to read
than 250,000,000,000 LOC even if it's wrong? How will you know when
it's wrong? Wait, that sounds like a really important question, so let
me rephrase it, HOW WILL YOU KNOW WHEN IT'S WRONG?
On Mon, Jun 20, 2011 at 12:49 AM, Ralf Westphal <in...@ralfw.de> wrote:
> On 19 Jun., 23:33, Curtis Cooley <curtis.coo...@gmail.com> wrote:
>> In an XP shop the communication of the design is going to be done with
>> the new programmer sitting down side by side with experienced
>> programmers and learning the design that way. I can not honestly think
>> of a better way to communicate the design of a system than sitting
>> side by side with another developer and actually working on the
>> system.
>
> Talking to someone surely always is better than being left alone with
> any form of design document, be it code or "formal documentation".
> But still the time needed to convey design should be used most
> efficiently and effectively.
> So I´m still wondering: If you want to work on some open source
> project which already has some 100K LOC, how do you best (most
> efficiently and effectively) get acquaintant with the project? By
> looking at the source code (including tests)? By looking at the source
> code together with an expert on that project? Or by looking at
> something else together with an expert?
>
I assert that keeping a non-executable design document in line with
reality on a 100K loc open source project is neigh impossible, so I
would learn the project by starting with the code closest to the area
I want to contribute. To get started contributing, and I have
contributed to more than one OS project, you do not need to grok the
entire project. Just the area closest to where you want to contribute.
That is the strategy I've used to learn and contribute to just about
every project I've worked on. need help with the GUI? I'll learn the
GUI and help with it. I don't need to know, yet, how the middle tier
talks to the web services. I just need to learn and model how the GUI
talks to the models and controllers, hopefully there are models and
controllers.
While at Expedia, I came up to speed enough in less than two weeks to
start contributing and doing stories. I did it by reading the code
closest to where I needed to contribute, and asking questions. If they
had a design document, I never saw it and they never offered it to me.
My bet is it was because they knew it was dreadfully out of touch with
reality.
Perhaps if you showed us an example document from an open source
project like the one you are talking about, I'd better understand what
you are looking for.
> Remember how you learned driving? Did the driving teacher start with
> detailed information about the process, the tool, and the
> infrastructure to get you going? Hardly.
> Where you nevertheless confused by details? I guess so. At least I
> was.
>
> Today you´re driving competently, of course. You´re shifting your
> awareness between an overall picture and details as necessary. But
> what you´re surely striving for is, to keep it at as a high level as
> possible. Because otherwise you would not be able to enjoy a scenic
> road :-)
>
Learning how to drive is not a good metaphor. I know how to code, I'm
just learning a new system. I think the metaphor would be more like,
if you were driving around in a new city, would you want an up to date
map of the city, or the high level design documents the city planners
used to design the layout back when the city was young and starting to
expand? I'll take the map, even if it has too many details. An
preferably the phone number of the destination.
That said, an in tune with reality high level design document that
perfectly explains how the current system is designed would be great.
I've just never actually seen one.
On Mon, Jun 20, 2011 at 8:59 AM, David Starr <da...@elegantcode.com> wrote:
> For those of us doing .NET dev, there is a technology in Visual Studio
> called layer diagrams. Think of it as a way to take that drawing we
> typically put on a whiteboard and map it to code. Draw a box, put classes or
> namespaces inside that box, then validate that those dependencies stay true.
> This has been amazing for communicating and enforcing design and then
> emerging it deliberately. It essentially gives us a picture of the system to
> talk to new devs about and somewhat enforces that design.
> It isn't UML, just the same level of modeling you would do on a whiteboard.
> The magic is in the CI build, where we get to validate the code against the
> higher level model and fail the build unless we stay true. If there is a
> legit reason to change, we discuss it and change the model.
> Has been genuinely trans-formative.
>
I think this is cool, and maybe the answer to what Ralph is asking
for. My biggest concern about 'formal' design documents is that they
get out of touch with reality and become useless. They actually lie.
This fixes that concern by turning the formal documents into
executable documents. It's easy to know when executable documents
diverge because the build fails. Kudos. I wish they had this for Java.
Perhaps they do, I'll start looking.
On 20 Jun., 10:02, Keith Brown <keith-br...@pluralsight.com> wrote:So you´re saying, the model of a software is just in the heads of
> No, that's not what I'm saying. In reality, whiteboard discussions + pairing
> is the way we communicate design at Pluralsight.
developers. And it needs to always be reproduced by some developer to
convey it to another. Or it has to be extracted from code.
Correct?
That means, probably the most complicated "machines" on earth (man
made systems consisting of inanimate parts) have a design which can
only be transmitted by oral tradition - or by reverse-engineering it
from the "machine" itself. (Since I´m talking about the structure of
the source code itself I don´t mean source code to be the design.)
That´s state of the art. That´s how you should do it. Have the design
in your head and code it. Or let it emerge through TDD and remember
it. To teach it, temporarily dump it onto a whiteboard, then erase it.
The recipient will have built her own mental model from the whiteboard
sketches. Don´t come back to any whiteboard sketches, don´t store
them, because they get out of sync immediately with the only source of
truth: the source code.
It does help us to explain why the view of the programmer as semi-unskilled
labor is not adequate.
>
>
> >
> > If you are doing it right, there will be a place where you can find your
> high level overview, for example in the IoC container config,
>
> Hm... you mean a loooong list of mappings from interfaces to classes
> is a valuable overview? It makes understanding the design of a system
> easier?
> And what if there is not such list because the DI container assembles
> the mappings automatically from executable files?
>
What about DSLs? Having different levels of abstractions, where the highest
level talks in domain terms in a very concise way?
> > But I have a feeling you want to suggest something even better.
>
> I sure have my point of view ;-) But I´d like to hear how the
> craftsmen community is doing it. How do they bring new people on the
> team up to speed.
> Is it like "Welcome, Joe, here´s 30.000 lines of code for you. Just
> prowl through them and you´ll know how this baby works. Just start
> with the tests, whip up the debugger and off you go."
>
The way we do it is by pair-programming with the new developer. I
think it's effective, even though our code is not as clean and
speaking as I would like it to be :)
Matteo
Perhaps it is the language barrier but you write here as if you are
incredulous that anyone could think anything like what we are
saying. Nonetheless ...
On Tuesday, June 21, 2011, at 8:16:40 AM, you wrote:
> So you�ソスre saying, the model of a software is just in the heads of
> developers. And it needs to always be reproduced by some developer to
> convey it to another. Or it has to be extracted from code.
> Correct?
That's not what I'm saying, nor is it what I hear others saying.
However, I am saying something similar:
First, the model that matters most is the one in the heads of the
developers, because that is the one that will have the most impact
on what they do and how they do it.
Second, the model in a developer's mind can be much richer than
anything that is readily transmitted via diagrams or written
words. The best writing is a poor copy of what the author knows,
and the best reading picks up only a poor copy of what is in the
written material.
Third, what we want is to have the greatest fidelity possible when
we try to move understanding from one mind to another. We would
like to have everyone understand everything we know. This is, of
course, quite difficult.
Fourth, the only document that is guaranteed not to be out of date
is the code. Any other document may or may not reflect what is
really there. The source code reflects what is really there.
Fifth, the source code contains much of the nuance of the
implementation. It says /how/ things are being done, always, and
if well written it can say what is being done and why.
Therefore, for maximum certainty about the program, and for
maximum detail, the better the source code communicates, the
better we'll understand. This cannot be discounted. Every good
programmer knows that when document and code conflict, the code is
the truth.
And therefore, for maximum understanding, direct communication
with someone who knows is invaluable.
The result of this chain of reasoning is that while we may find
other documents to be helpful and valuable in entering into
understanding, we prefer to rely heavily on the source and on
those who already understand. With those who understand, we prefer
conversation. With the source, we prefer source that expresses the
various ideas of how, what, and why as well as possible.
> That means, probably the most complicated "machines" on earth (man
> made systems consisting of inanimate parts) have a design which can
> only be transmitted by oral tradition - or by reverse-engineering it
> from the "machine" itself. (Since I�ソスm talking about the structure of
> the source code itself I don�ソスt mean source code to be the design.)
In the source code, if a design idea is not put in, it is not in the
final product. The source code, in a very key sense, is the final
and definitive statement of the design.
It's true that sometimes reading source code feels a lot like
"reverse engineering" as we try to decode what the heck the author
was doing. We try to write code so that this is not necessary, so
that the code more directly expresses what we are doing, why, and
how.
> That�ソスs state of the art. That�ソスs how you should do it. Have the design
> in your head and code it. Or let it emerge through TDD and remember
> it. To teach it, temporarily dump it onto a whiteboard, then erase it.
> The recipient will have built her own mental model from the whiteboard
> sketches. Don�ソスt come back to any whiteboard sketches, don�ソスt store
> them, because they get out of sync immediately with the only source of
> truth: the source code.
I'd say:
> That�ソスs state of the art. That�ソスs how you should do it.
That's the essential truth of the art: it is how we must do it.
> Have the design in your head and code it.
We must have the design in our head in order to code it. (Clearly
it is not possible to code something that does not pass through
our head first.)
> Or let it emerge through TDD ...
We are unlikely to create a perfect design in our head or on
paper: when the design meets the code, the code needs to have a
say. In addition, there is great value to having parts of the
program sooner, both in terms of customers learning what they
really wanted, and, often, in terms of their receiving actual
value from using the program.
If we are going to build the system as we go, we need a strong
framework of tests and a design that always includes and shows our
improving design ideas. Therefore we use TDD (red/green/refactor)
to drive out the design, protect it, and keep it clean.
> and remember it.
We need to remember it, that is, to have it in our heads, in order
to work effectively with us. Therefore, we write the code to be as
memorable, and as clear, as possible. We would like, as we read
it, to be reminded of the design ideas we had when we wrote it.
> To teach it, temporarily dump it onto a whiteboard,
To talk about the design, diagrams may be helpful. The best
diagrams seem to be those drawn in the moment. These both reflect
the ongoing conversation better, but also, somehow, the physical
act of drawing seems to help things go into our minds more easily.
This is not a "dump". On the contrary, it is a selective view of
all that we understand, custom fitted to the thing we are
communicating in that moment. Thus, it is much more suited to
talking about the important matters than any comprehensive
document, paper or whiteboard, could ever be.
> then erase it.
Or save it if you like. But the next picture will probably be
better, more applicable, and more suited to the moment.
> The recipient will have built her own mental model from the whiteboard
> sketches. Don�ソスt come back to any whiteboard sketches, don�ソスt store
> them, because they get out of sync immediately with the only source of
> truth: the source code.
More importantly, like any such document, no matter how large or
small, they are out of sync with the question of the moment. Every
drawing, every document, represents the subset that its author
thought important at that moment. A live diagram, with a
conversation, reflects what both participants think is important.
As such, every new joint document is the best document we could
have at that time.
> Correct?
Not really. I find myself wishing you were trying more actively to
understand what we are saying. Remember, please, that most of us
here have known how to do traditional documentation for many years
and have come to this viewpoint not through some path of chaotic
hacking but through long experience trying to do our best.
Ron Jeffries
www.XProgramming.com
Do as you will, try to do it well. That's what I do.
Why are we so concerned about reading source code? I get the feeling
that some people are adverse to actually reading source code. I get
this feeling when we talk about design documents or when I say to my
colleagues at work that comments are a code smell. I get the feeling
some developers feel it's better to write an English (or German or
Cantonese or UML) comment than have the code express the intent.
Uncle Bob, I think in Clean Code, talks about how even during a
development session we read, and I forget the real numbers, like 10
times more code than we write, so mastering how to read code is
essential. If you read his books they have tons and tons of code in
them, because learning to read code is important. Leaning to read code
is important because only the code expresses the reality of the
system.
We don't <em>need</em> oral tradition or whiteboard sessions or design
documentation to learn a system. I learned the Expedia architecture by
reading the code. I learned the various OS projects I've contributed
to by reading the code.
Is reading the code the only way to learn a system? Probably not. Is
it the best way? It depends. It is the only way you can be certain you
are learning the real system, but I can imagine there are better ways.
I augmented reading the code at Expedia by asking questions of the
people who knew the system. Those people didn't write it though. They
learned the system the same way I did, by reading the code and asking
questions.
Anyway, I'm missing the reason for the aversion to reading code. Can
anyone explain why it's not a good idea to read code and master
reading code?
and that is why we should be using programming language systems that
let us more directly, clearly, succinctly, accurately, verifiably, say
what we mean. so we should be using higher level languages, dsls, etc.
rather than painful boilerplate bog-standard java or whatever.
$0.02.
Sure. There will be a lot of debate over which ones do this, and
when. In the end, I think we need to be able to learn to read what
we get. Over a wide range of languages, I can do that. In the case
of some (you know who they are), I have less luck. :)
Ron Jeffries
www.XProgramming.com
In times of stress, I like to turn to the wisdom of my Portuguese waitress,
who said: "Ol�, meu nome � Marisol e eu serei sua gar�onete."
-- after Mark Vaughn, Autoweek.
> So the pendulum came to swing into the other direction: "paper
> aversion" ;-) "We need only the source code. All else... well, it�s
> left to you. Whatever you find valuable for your team."
> That�s where we�re now.
Well, yes. I'd rather see such decisions made by the team than some
outside agency. That said ...
> And one of the effects I see again and again: Teams do not architect
> their solutions and do not know what the design of their solutions is.
> They lived by the day producing heaps of code. And what�s worse: They
> are unable to communicate efficiently and effectively about what they
> are doing. They don�t have a common and unambiguous language for
> designing software.
What you describe here does happen. I believe it would happen no
matter what we told such a team to do because they are some
combination of incompetent or under such pressure as to revert to
panic-driven behavior. Either way no amount of our telling them to
TDD, nor to draw pictures nor write words, is going to solve their
problem. Their problem is inside them.
> (No, I�m not suggesting UML is the solution to that. UML very
> rightfully is not in broad use at least within the community I�m
> working with. Maybe 10% of devs are using UML. UML just produces too
> formal models.)
Yes. I like a nice little whiteboard diagram with circles and arrows
and such. And boxes. What do you like?
> So what can we do? Is TDD gonna save the world? I doubt it. It�s "peep
> hole software development" ;-)
It's not peep hole the way I do it, because I know how to do it at
every level, and how to express many things, at many levels, clearly
in code.
That said, it can certainly be done in a peep hole fashion, and it
can be quite difficult to get the big picture if it is.
> There needs to be a truely usable
> approach to software design for more coarse grained structures before
> coding. Easy to teach, easy to use, producing understandable and
> durable results, staying in sync with code, supporting collaborative
> design.
It would be nice to have a usable approach to dealing with coarse
grained structures. I do not see that I'd do much more "before
coding", though, as this is not a good time to make final decisions.
I'd see using it all through the process if it were usable that way.
I'm not aware of such a thing existing. Do you have candidates in
mind?
Ron Jeffries
www.XProgramming.com
Get over it. -- The Eagles
> I�m looking for ways to change it. I realize the pain it gives me to
> be forced to stare at source code. I don�t consider it fun. And I feel
> hindered in solving a clients problem. Yes, I need source code - but
> that does not mean I need to like it.
Maybe, in all seriousness, you just don't like programming?
Ron Jeffries
www.XProgramming.com
Accroche toi a ton reve. --ELO
as a long-time programmer who tries to be on the look-out for better
ways of doing things, i'd like to say that we'd have to define
"programming" and that most of what people call programming is bad
stuff that we're generally too dumb and too uncreative to get rid of
and change for the better.
I'm sure there is a way to generate high level diagrams from code.
I've seen a couple of posts pointing to tools that claim to do that,
but I've yet to dig into them, being the skeptic that I am. I was
burned by TogetherJ, and that whole fool me once thing you know.
Generating source code from high level diagrams though, which is where
I assume Ralf is going? I'm really skeptical. You can reduce the
resolution of an image, but once you've done that, you can never get
it back. You've lost information.
I assert a diagram or model that meets Ralf's requirements for being
easy to communicate and understand, loses enough details that the
source can not be regenerated. Anyone who ever used a UML tool to
generate diagrams can testify that the resulting diagrams were so
detailed and verbose as to be mostly useless. When they weren't, they
lost crucial information, and could not be used to regenerate the
code.
I can image a tool that provides an alternate view of the source
code. Keeping the details required to run the system, but only
displaying the "architecture". I know lots of people have tried to
make money building such things. I'm not sure any actually did.
> So if you want to discuss stuff seriously with me, please try to
> attack my arguments, not my likings.
Oh. I understand now. You didn't like my question, took it somehow
as insulting, so you gave me some back. OK.
Ron Jeffries
www.XProgramming.com
Will Turner: This is either madness or brilliance.
Captain Jack Sparrow: It's remarkable how often those two traits coincide.
I completely agree with this. I agreed with it in 1990. I agreed with
it in 2000. I agree with it now. I hope that it actually happens and
sticks while I'm still in this profession. Until then, I take the
Agile and Craftsmanship Manifestos to heart in that human interaction
is more effective than any other form of communication. No design
model will ever exist that will replace human interaction with the
designers. Well, maybe holographic interactive representations of the
designers that react and respond to questions. Having reliable
documents as a temporary substitute would be great.
Today, when I go to work, my best bet at learning more about the
system is going to be reading the code and whiteboard design sessions.
If there was a better way I'd use it. I'm not tool adverse, I just
don't want to be tool dependent like so many ctrl-space developers
that never bother to actually learn the API to the library they are
using.
I'm beginning to struggle with the point of this whole discussion
thread. If a tool existed like the one Ralf describes, I find it hard
to believe any of us on this list would not employ it at some level.
It doesn't, though, so we cope as best we can.
Because reading source code and whiteboard design discussions work
well enough for me that I have higher priorities than taking on a task
that so many have tried and failed at.
> Why just "we cope as best we can"?
There are limits to what I can accomplish, so I use the tools I have
and improve the tools I need to improve. Building a tool to
reconstitute design models from source code is way way down on my
list. While I agree I would use a tool if it existed, I do not suffer
as much pain as you do from reading source code and drawing on a
whiteboard. A static model printed on paper is not dynamic enough for
me. A discussion around diagrams drawn on a white board are dynamic. I
learn better in dynamic situations and it does not cause me any pain
what so ever to draw a diagram in a whiteboard.
> Why not sit down and write up what we want/need - and then find a way
> to get it?
>
I do that quite a lot. At the risk of repeating myself, another
TogetherJ tool never makes it on that list.
> So many devs working on all sorts of nitty gritty detail technology
> like OR mappers, testing tools, DI containers, CQRS frameworks... That
> ´s all nice and well. But why isn´t there any effort (within the
> craftsmen movement) to improve the fundamental situation we´re
> suffering from? That is: re-creating models from code is damn tiring
> (but seems less tiring than keeping separate models in sync).
>
Seems to me those developers are addressing their pain points. Writing
SQl in code was painful and error prone, so we developed ORM.
It seems to me the answer to your question is that no one else feels
the pain enough to build such a tool. Which, by the way, is far from a
trivial task.
> So many devs working on all sorts of nitty gritty detail technology
> like OR mappers, testing tools, DI containers, CQRS frameworks... That
> ´s all nice and well. But why isn´t there any effort (within the
> craftsmen movement) to improve the fundamental situation we´re
> suffering from? That is: re-creating models from code is damn tiring
> (but seems less tiring than keeping separate models in sync).
>
I assume it is because of the following (you already answered it in an earlier mail and Arnaud made the point):
Am 23.06.2011 um 09:27 schrieb Arnaud Bailly:
> I mean really two obvious things:
> 1. Most language I know of are full of boilerplate code, magic incantations and unnecessary noise that gets in our way when we want to abstract and generalize. With the possible exception of Lisp and Haskell and possibly others, most PLs are really idiosyncratic and limits the capacity of removing duplication and synthesizing concepts,
> 2. Most coders I know of (and I include myself in the bunch) are more skilled at writing for machines than writing for humans.
>
Most programmer do not design they do programs. If a tool would exist to show the design the tool would simply implode. :)
On the other hand: if you are in a team of good programmers that do design the design is often easily readable in the code. These people just do not need another tool. They are happy with what they have and busy teaching and helping others.
> I don´t want to get tired by this any longer. I want to free up my
> head to solve problems, instead of reverse engineer code or sync
> mental models at the whiteboard. I want to collaborate with my team
> members to implement new functionality. Easily. Without being bogged
> down by code which is an implementation detail of any solution.
> Solutions are conceptual in the first place; code is just a tool.
>
I join you in feeling the pain to not have graphical representations of your mind, but this is a problem that covers many aspects of communication and not only software. Let's start with that one:
Let's find an easy way to give people the ability to express what they mean. Let's assist them with software to do that. I am quite sure that if we succeed in this, it will be only a small step to transform the results to software and vice versa (software to visible expressions of meaning)
Andreas
> If you agreed with me all along, and if such a tool does not exist...
> why aren�t you trying to improve the situation?
> Why just "we cope as best we can"?
> Why not sit down and write up what we want/need - and then find a way
> to get it?
Here's a snippet from Bob Martin's new book, The Clean Coder, that
seems to me to bear on this discussion:
==============================================
In the early '90s I was very hopeful that the CASE tool industry
would cause a radical change in the way software developers worked.
As I looked ahead from those heady days, I thought that by now
everyone would be coding in diagrams at a higher level of
abstraction and that textual code would be a thing of the past.
Boy was I wrong. Not only hasn't this dream been fulfilled, but
every attempt to move in that direction has met with abject failure.
Not that there aren't tools and systems out there that demonstrate
the potential; it's just that those tools simply don't truly realize
the dream, and hardly anybody seems to want to use them.
The dream was that software developers could leave behind the
details of textual code and author systems in a higher-level
language of diagrams. Indeed, so the dream goes, we might not need
programmers at all. Architects could create whole systems from UML
diagrams. Engines, vast and cool and unsympathetic to the plight of
mere programmers, would transform those diagrams into executable
code. Such was the grand dream of Model Driven Architecture (MDA).
Unfortunately, this grand dream has one tiny little flaw. MDA
assumes that the problem is code. But code is /not/ the problem. It
has never been the problem. The problem is /detail/.
DETAILS
Programmers are detail managers. That's what we do. We specify the
behavior of systems in the minutest detail. We happen to use textual
languages for this (code) because textual languages are remarkably
convenient (consider English, for example).
...
The hope of the MDA movement was that a great deal of detail could
be eliminated by using diagrams instead of code. That hope has so
far proven to be forlorn. It turns out that there just isn't that
much extra detail embedded in code that can be eliminated by
pictures. What's more, pictures contain their own accidental
details. Pictures have their own grammar and syntax and constraints.
So, in the end, the difference in detail is a wash.
==============================================
Mind you, this doesn't go to say that better tools can't be made,
nor that programmers couldn't be better. They could be, and they
could be.
However, given the state of things today, I am inclined to work on
improving programmers' ability to express design in the languages of
today. I'm confident, as Bob is, that those skills will not become
obsolete any time soon.
Ron Jeffries
www.XProgramming.com
Those who believe complexity is elegant or required don't understand
the problem. -- John Streiff
> I mean really two obvious things:Sure, we´re suffering from language problems.
> 1. Most language I know of are full of boilerplate code, magic
> incantations and unnecessary noise that gets in our way when we want to
> abstract and generalize. With the possible exception of Lisp and Haskell and
> possibly others, most PLs are really idiosyncratic and limits the capacity
> of removing duplication and synthesizing concepts,
> 2. Most coders I know of (and I include myself in the bunch) are more
> skilled at writing for machines than writing for humans.
And I don´t think this is gonna improve as long as we remain in the
textual source code area.
C# or Java or VB or Ruby or Clojure or Scala... that does not make a
big difference.
It´s all one dimensional textual representations. And they all suffer
from the same difficulty to express different levels of abstraction.
Let´s take a better look at the emperor: *diagrams* are simplistic,
have fewer symbols and shades of meaning in the language,
one-dimensional, inefficient, incapable of abstraction, and can´t do
the job text has been doing for years. If it were not necessarily so,
we´d be programming in pictures, since it´s not hard to write a
program to find squares and circles and lines and arrowheads in a
picture, or to represent the same in a little language. And there´s
the point: diagrams are a little language, one that´s not anywhere as
rich as the programming languages we use daily.
We should look instead for languages with more powerful engines behind
them, that let you express higher ideas with less effort. For
example, Haskell gives you the mechanisms of functional programming
and category theory, which for certain classes of problems results in
an order of magnitude less code. This is still text, but is a better
result than pictures ever gave us in programming.
Jason Catena
> Hello Ralf,
>> It´s all one dimensional textual representations. And they all suffer
>> from the same difficulty to express different levels of abstraction.
>>
>
> This is probably where I (albeit slightly) disagree with you and might feel
> closer in this respect with Ron or Curtis. Visual representation is
> extremely efficient yet maybe not as much as textual for conveying *at the
> same time* various levels of details. And it is this back and fro travel
> from details to big pictures which I currently miss. I would rather feel the
> urge to improve our textual representations, possibly allowing more
> dimensions to be used than simple linear text, and possibly allowing easier
> embedding of geometric information about code, than jumping into the model
> extraction wagon.
>
> Regards,
> Arnaud
> Regards,
> Arnaud
On Sat, Jun 25, 2011 at 15:51, Ralf Westphal <in...@ralfw.de> wrote:
> Alas, I guess, this is impossible. Even the cleanest code of all
> suffers from its "textualness". It´s just plain text. And text is - as
> I already mentioned - inherently single dimensional. There is only one
> point to start reading it: at the top. And then it runs down a page.
>
> Text is a very, very poor representation of mental models. Like a byte
> array is a poor representation of an object graph.
While it is still not a good representation of the mental model, the
navigable view of code that is presented by the more advanced IDEs is
a step in the right direction. EiffelStudio takes it a little further
by enabling manipulation of code by visual metaphors (pegs and holes).
The Code Bubbles IDE looks like it has potential to take steps in
another direction in order to break free of the one-dimensionlity of
text. Actually, the Smalltalk environment did that too, a long time
ago.
-----
On the other hand, an application is more than just the code. The code
describes the static view, but for example in an application built
with actors or agents, the runtime structure (how these actors
interact, move around, update their code, etc) is just as important.
Of course, this is visible somewhere in the code, but it's much more
difficult to see than for example algorithmic issues.
There is also the issue of third-party code. Do I have to read their
code in order to understand what they do? No, the API description is
enough. But isn't it a formal documentation, thus bound to fall out of
sync?
----
I don't know, I'm just making waves because I learned a lot since Ralf
started to do too :-)
best regards,
Vlad
I guess that what I'm trying to come at is that there are
circumstances where reading the code and asking gurus in order to
understand a code base is impractical. 3rd party libraries, frameworks
used, other infrastructure, legacy applications: the only way to
understand them is by means of documentation that is at a higher level
of abstraction than code, if not for other reason then only because of
the sheer amount of code that is at stake (and many times, the source
code is not available anyway).
Also, there has to be some way to indicate what the code is meant to
do. Reading the code will tell what it does, which might be not what
was intended. Tests (unit or otherwise) are a good way to formalize
this in code, but there are some issues with them: they can be wrong
too (may not cover all the corner cases or test the wrong thing, for
example) and legacy applications don't have them (or not enough of
them). There should be a way to document that even in these cases,
right?
I'm all in for just reading the code and have the design in the heads
of the team, but what I wonder if it works beyond a certain size of
the application? I'm working with a system that is developed by ~15
teams with ~15 people each, a huge code base in several languages,
some parts dating from over 10 years ago. I certainly can't have all
of it in my head, barely that for the subsystem my team develops. So I
need to be able to refer to the other subsystems by some high-level
documentation, because the guys in the other teams are not always
available to ask. Consequently, our team has to provide documentation
for the others to access. Sure, the documentation gets out of sync
sometimes, but then I only have to disturb someone to only explain the
diff, not the whole thing.
If anybody has suggestions about some other way to handle this, I
welcome them warmly.
best regards,
Vlad
Jason Catena
Yes, it certainly is. Does that mean that we're doomed not to be able
to be craftsmen? Do you have any suggestions as to how the
organization and thus the code should ideally be structured, so that
everybody can have all the source-code-only based design in their
heads?
regards,
Vlad
> Yes, it certainly is. Does that mean that we're doomed not to be able
> to be craftsmen? Do you have any suggestions as to how the
> organization and thus the code should ideally be structured, so that
> everybody can have all the source-code-only based design in their
> heads?
There is probably no need for all the people from all your teams to
have all the design in your heads, any more than we all need to have
all the design of our compilers and operating systems and tools in
our heads.
I don't think anyone here is saying that all communication about
design should come from source code. Some of us are saying,
//because we know how to do it// that much more design can be
expressed in source code than typically is. We are also saying that
we think it is a good idea //for several reasons// to code that way.
In your situation, if I had the ability to influence the
organizational structure and interfaces, I would be inclined to use
tests (source code) to communicate between teams, which would
express the interface by example and, through being executable,
provide a concrete assurance that teams' new versions did not break
the system.
Doing this would likely reduce the need for other written
documentation, and might not eliminate it. There would also be
useful diagrams and such, I would imagine ... and I would still
expect to find that the diagrams drawn in the moment would be more
useful than paper or on line ones that just float around.
Ron Jeffries
www.XProgramming.com
I could be wrong, but I'm not. --Eagles, Victim of Love
On Sun, Jun 26, 2011 at 10:56, Ron Jeffries <ronje...@acm.org> wrote:
> There is probably no need for all the people from all your teams to
> have all the design in your heads, any more than we all need to have
> all the design of our compilers and operating systems and tools in
> our heads.
>
> I don't think anyone here is saying that all communication about
> design should come from source code. Some of us are saying,
> //because we know how to do it// that much more design can be
> expressed in source code than typically is. We are also saying that
> we think it is a good idea //for several reasons// to code that way.
Thanks for the answer. One problem with discussions like this, where
basically someone "makes waves" in order to stir a community and open
up fresh angles on a subject, is that everyone comes with their own
preconceptions and points of view. Most of the time, it's not possible
to understand the other person's POV right away and thus it happens
often that people talk past each other. Looking back at this thread,
I can see that you are probably right and that was what was meant, but
at first reading many posts seem to be much more dogmatic (in the lack
of a better word). Maybe it's my non-native English showing through.
Maybe it's the benefit of hindsight.
> In your situation, if I had the ability to influence the
> organizational structure and interfaces, I would be inclined to use
> tests (source code) to communicate between teams, which would
> express the interface by example and, through being executable,
> provide a concrete assurance that teams' new versions did not break
> the system.
There's work in that direction, it will take some time until it gets somewhere.
> Doing this would likely reduce the need for other written
> documentation, and might not eliminate it. There would also be
> useful diagrams and such, I would imagine ... and I would still
> expect to find that the diagrams drawn in the moment would be more
> useful than paper or on line ones that just float around.
A problem with an extended team of 200+ people is that there is a lot
of movement - people come and go, change functions, etc. Finding the
person who can answer a specific question isn't always
straightforward. Usually these persons are in demand from many places,
so it's difficult to find a time to talk to them.
Personally, when approaching a new code base, I prefer the following sequence:
- read some overview of the architecture and design, to get the feel of it
- having identified the key places in the code, use them as starting
points for browsing
- if some things are unclear, I try to find a documentation of what is
the intention of that code; i am aware that it might be out-of-date,
but spotting a mismatch means there's either a bug or the doc needs
updating, so I create a ticket for that
- when I know which questions to ask, I go ask someone who knows; I
wouldn't want to waste their time with a question whose answer was
glaringly obvious from easy accessible docs/code.
best regards,
Vlad
except for all those ways in which tests can't prove that ;-)
In all my years I have never /once/ encountered a situation where
tests could not have covered the problems that turned up. The theory
is interesting but for most of us, most of the time, it is the
practice that is lacking.
Ron Jeffries
www.XProgramming.com
I'm really pissed off by what people are passing off as "agile" these days.
You may have a red car, but that does not make it a Ferrari.
-- Steve Hayes
Peter Naur developed a counterposition to the idea that documentation
of any kind _including the source text_ can fully take the place of
learning from someone who already knows the theory of the program. To
answer your question, what is it that we should do, read at least the
last two sentences in the quote below. (Though, to fully understand
what he means, the rest of the paper helps.:) In essence, he's
saying: throw your new developer at the task of actually doing
something to change the program, and coach them through their work and
misunderstandings. Further, Naur says this is the only way to really
do it.
From http://dl.dropbox.com/u/502901/naurtf.pdf :
"The extended life of a program according to these notions depends on
the taking over by new generations of programmers of the theory of the
program. For a new programmer to come to possess an existing theory
of a program it is insufficient that he or she has the opportunity to
become familiar with the program text and other documentation.
What is required is that the new programmer has the opportunity to
work in close contact with the programmers who already possess the
theory, so as to be able to become familiar with the place of the
program in the wider context of the relevant real world situations and
so as to acquire the knowledge of how the program works and how
unusual program reactions and program modifications are handled within
the program theory.
This problem of education of new programmers in an existing theory of
a program is quite similar to that of the educational problem of other
activities where the knowledge of how to do certain things dominates
over the knowledge that certain things are the case, such as writing
and playing a music instrument. The most important educational
activity is the student’s doing the relevant things under suitable
supervision and guidance. In the case of programming the activity
should include discussions of the relation between the program and the
relevant aspects and activities of the real world, and of the limits
set on the real world matters dealt with by the program."
Managers and companies don't like or believe in the idea that someone
isn't replaceable by documentation or a program, since they then need
to actually value talent and experience in their employees, instead of
simply making jobs disappear into the technical apparatus of the
company (see http://en.wikipedia.org/wiki/Scientific_management#Later_decades:_making_jobs_disappear).
Jason Catena
> What I�m missing, though, is any hint or recommendation how to plan or
> communicate design other than with source code.
> Except the repeated statement: "Draw something on the whiteboard if
> you like."
> TDD has been defined rigorously by the XP community. It is precise
> about code.
> But unfortunately I feel it lacking the same precision where the
> discussion goes beyond code.
> So what�s the contribution of XP or software craftsmanship to larger
> projects? (Where "large" of course is quite subjective and relative;
> what I find large might be just medium to you. And usually a system I
> don�t know yet to me seems larger than a system of equal size but
> which I built myself.)
> Should our industry live by: "Use TDD and source code as much as
> possible - and beyond that invent your own style. Just keep talking at
> the whiteboard."
> Is that what you�re saying?
No, that's not what I'm saying. Or at least not nearly all that I am
saying.
You seem to be all about wanting some really great other ways to
communicate, but perhaps because of all the excitement, the only
thing I've really managed to receive from you is a rejection of TDD
as not good enough.
What positive, actionable recommendations would you offer, and how
would you blend them in with other things like TDD?
Thanks,
Ron Jeffries
www.XProgramming.com
Confidence has nothing to do with perfection.
It has to do with a quality of deep self-acceptance
that leads us to do things in a masterful way,
as it allows us to speak our mind and our hearts. -- Agapi Stassinopoulos
hmm, ok, i'll definitely take that as serious food for thought.
thanks,
It's a really interesting discussion here.
Did you ever think of how a great novel could be expressed in pictures and sketches?
Sometimes text may just be the right level to express something.
Cheers
Andreas
This is pretty cool sounding, and I'll try to look into it deeper
because I think I'm missing a key ingredient. The key ingredient I
don't see is which part of it solves the Design/Code paradox*? This
reminds me of reading Peter Coad for the first time. It all sounds
great and I'm following along just fine, but then I turn the page and
there was some hand waving and incantations that I missed that get to
the current state of the model. I keep squeezing the pages between my
fingers to see if maybe they were stuck together, but to no avail.
Like the step between:
* The design is visual which allows for quick communication.
* The design can be translated losslessly into code; it also can be
regenerated from code.
If you look at a picture and Ron looks at a picture and I look at a
picture, we are all going to come up with different narratives about
the picture. Unless the picture has so much detail that the narrative
is not interpretative. Then I assert it will not allow for quick
communication.
* Design/Code Paradox: For a design to be easy to understand,
refactor, and share, it needs to be abstract and non code centric. For
a design to be easily converted into code, it needs enough detail to
for the programmer to convert it correctly. There's a details paradox:
if it's too abstract, it can not be converted into code easily and
correctly. If it's detailed enough to be converted easily and
correctly into code, it's not abstract enough to be easy to
understand, refactor and share.
--
Curtis Cooley
curtis...@gmail.com
blog:http://ponderingobjectorienteddesign.blogspot.com
===============
Leadership is a potent combination of strategy and character. But if
you must be without one, be without the strategy.
-- H. Norman Schwarzkopf
the other mode: S-mode (s for self-centered) makes you say "oh
everybody on earth must think the way i do and only like what i like
and if you think otherwise you are obviously a clueless cretin and get
off my lawn" :-)
that this can be sorta meta in that if you are already Anti-S-mode you
might be in a higher-level S-mode :)
> I wonder whether I´m the only one feeling a tension between one
> dimensional textual representations of a design and the actual
> multidimensional reality of a design.
No, you are not alone. There are at least two of us.
I have been reading this thread with some fascination and agree far more strongly with you than with most of the other commentators. Because I'm coming to it late, I'm combining a few responses to hopefully make even more sense than scattered replies. I'm also starting by replying to points from a few days ago.
I work on systems where the team is dealing with 1 - 2 MILLION lines of C++ code. The only people who have most of the models of how that works in their heads have been with the company for years and even they get it wrong.
The models in documentation can be audited against software. The models in heads can't without each individual doing that auditing.
Like you, I've been doing this for around thirty years and in a wide variety of languages, platforms and architectures.
Ron keeps making the point that the code says what the system DOES.
That's correct.
It doesn't help you when you're trying to work out what the system SHOULD do.
Yes, documentation goes out of date and there's a need to keep it up to date (that's one reason I'm a big fan of using tools like doxygen and keeping it as close to the code as possible).
However, the RATE at which documentation goes out of date is in direct proportion to its level of abstraction from the code. I see that Vlad raised the point of working on big systems with distributed teams (he even has more teams than we do).
Above a certain size of code, if even high level documentation is going out of date rapidly, I contend that you have other problems and a recipe for an unstable, buggy system. (Again, a point Vlad made later.)
I actually like programming, in fact I love programming and I love reading code and read other people's code for fun and education. I want better tools to make that a smarter reading experience (I'm still mourning the Object Master environment for editing C++ in a Smalltalk-style OO manner). I have a deep suspicion that being able to combine annotating tools, diagrams and code will help. I've been frustrated and amazed for the last twenty years that OO diagramming tools are generally poor at letting you compare alternative ideas about a design - that is the fundamental of my design practice.
> I´m passionate about my profession and am
> unwilling to just live with the painful status-quo of having to stare
> at source code to extract a helpful model that once was on a
> whiteboard.
Absolutely!
Except in many cases getting them to take a few minutes to discuss it on the whiteboard would also be progress!
@Curtis
> I take the
> Agile and Craftsmanship Manifestos to heart in that human interaction
> is more effective than any other form of communication.
Agreed, when the humans have the information to convey and (sometimes) if they have the time.
Above a certain size, you can't expect people to retain models indefinitely. We have an utterly awesome VP of devleopment who constantly amazes me as to how much legacy knowledge he has retained but, seriously, just how much of his time should one programmer expect to grab?
@Ralf
> So many devs working on all sorts of nitty gritty detail technology
> like OR mappers, testing tools, DI containers, CQRS frameworks... That
> ´s all nice and well. But why isn´t there any effort (within the
> craftsmen movement) to improve the fundamental situation we´re
> suffering from?
My simple (and cynical?) answer is that it's a lot harder. The design and implementation of plumbing requires a different mindset.
Sounds like you have an unsustainable code base. Do you refactor it
in part regularly to keep its theory fresh in people's heads, or just
let it sit and rust until part of it falls off?
> The models in documentation can be audited against software. The models in heads can't without each individual doing that auditing.
I submit that audits and documents are both less important than the
heads that update the code to keep it working. What good is audited
documents anyway if not in people's heads? Why are documents more
valuable than people who know your program? This isn't (yet) an
assembly line, where you can throw a training pamphlet at someone for
an hour and then put them in the place of the guy fired yesterday
because he wouldn't stop talking about better ways to do things.
> ...
>@Ralf
>> I´m passionate about my profession and am
>> unwilling to just live with the painful status-quo of having to stare
>> at source code to extract a helpful model that once was on a
>> whiteboard.
With a higher-level programming language or DSL (new textual ones come
along all the time, and can be worth the effort to create), bits of
the model commonly agreed can be codified, which I contend is better
than pictured.
Jason Catena
On Wed, Jun 29, 2011 at 16:06, Jason Catena <jason....@gmail.com> wrote:
> On Tue, Jun 28, 2011 at 22:44, Andy Dent <de...@oofile.com.au> wrote:
>> The models in documentation can be audited against software. The models in heads can't without each individual doing that auditing.
>
> I submit that audits and documents are both less important than the
> heads that update the code to keep it working. What good is audited
> documents anyway if not in people's heads? Why are documents more
> valuable than people who know your program? This isn't (yet) an
> assembly line, where you can throw a training pamphlet at someone for
> an hour and then put them in the place of the guy fired yesterday
> because he wouldn't stop talking about better ways to do things.
I don't think anybody said that documentation is _more_ important than
what's in the heads of the people. From my point of view,
documentation that is good enough (let's say 80% up to date) helps
anyway by for example letting new people get a general overview of the
system by themselves and then have a guru spend much less time
explaining. Usually the people that have all the design in their heads
tend to be very busy and it doesn't feel very efficient to have them
to chaperon the new guys.
An objection to the above might be that everybody in the team should
have the design in their heads, but in practice some may be less good
at explaining, some may be busy in several teams and some may be
smarter than others. Besides, for a large project, it may be too much
to have it all in the head.
In other words, if having written documentation as a complement to the
code and what's in people's heads works for some
people/teams/projects, then it means it works for them, right? Why
should they be chastised?
best regards,
Vlad
Am 30.06.2011 um 12:13 schrieb Ralf Westphal:
> So, would you still say, "pure text" has any advantage over "graphical
> languages" per se?
>
It is not about being "right" or "wrong" and not "good" or "bad". For me, it is about what helps in which context. Your examples are great to show that pictures (graphics) can help to transmit a meaning easier. And even there they combine it with words, because the pictures alone are not suitable to give the whole picture in themselves.
I was thinking of novels where the author gives us a multi-dimensional impression of a world; the inner of the people, multiple plots in parallel, details and so on. I think for many kinds of message words are really appropriate, because they make it easy to express complex realities with lots of detail.
>
>>
>> Sometimes text may just be the right level to express something.
>
> Maybe there are "stories" best told by using just plain text, e.g. a
> Shakespearian sonnett.
> But my guess is, that pure text is just best where the main point are,
> well, words and their sound.
I never hear sound when reading. Sound is on a different level, close to music. Instrumental music, for example, is something by which you can express emotions and moods, but you cannot be sure that your listeners all receive the same mood or emotions (which is absolutely OK and intended).
> Or where the very purpose of a text is to evoke images/emotions, i.e.
> where it´s not important or even contraproductive to get a predictable
> result. Literary authors would probably favor a difference in what
> kind of images they instill in their readers.
See above (music).
> But as a technical author (read: programmer) I´m interested in
> precision, in lossless replication of my images in the heads of my
> recipients.
And that is the point: Words - or better: language - is very appropriate here. If you go even deeper to the spoken word you have the advantage to listen to what your listeners received: They can explain in their own words. And you can then decide if this seems to be what you intended to.
Finally:
I love your idea of expanding the vocabulary of developers by graphics. I just cannot imagine getting rid of textual programming at all.
Andreas
> This is what makes FD special, I�d say: It does not throw out OO or
> TDD, but assigns them a particular place. OO is for implementation,
> not for thinking :-) TDD is for implementation of small (!) functional
> units (operations). To have the design implicit in code for small
> units of code is ok. 2-3 screen full of code are ok to stare at to
> decode the design. That�s also the level of detail that changes most
> often.
How do you determine whether the FD you draw is the FD that
implements what you understand the problem / solution to be?
Ron Jeffries
www.XProgramming.com
And thirdly, the Code is more what you'd call guidelines than actual rules.
-- Barbossa
I think its failure as a graphical communication language proves that programmers need to respect appropriate specialists! People who can't draw shouldn't be creating the building blocks for the rest of us.
It was a sad compromise, I thought Booch's original clouds were better, and sadder still is the fact that much better graphical communication languages for OO design were beaten down by the market forces - quality of communication was not an important factor compared to the Rational sales machine.
Scott McCloud's "Understanding Comics" was recommended by the head of Apple's user interface design group as reading for every programmer and software designer.
> UML was designed without any input from graphic communication
> professionals (as stated in a direct response from Grady Booch to
> my asking that question on the mailing list at the time).
> I think its failure as a graphical communication language proves
> that programmers need to respect appropriate specialists! People
> who can't draw shouldn't be creating the building blocks for the rest of us.
I mean this is fun, though it has an edge:
While in fact I agree that graphical designer might have helped with
UML, I must point out that the above paragraph proves that proofs
should not be done by people who can't do logic.
Ron Jeffries
www.XProgramming.com
I stand for excellence.
I'm tired of people who stand for less. -- Mike Hill
After a brief look at your web pages (I intend further but want to get this in the thread of email) I think I know some fellow-thinkers :-)
I have a suspicion you'd find some useful similarities in Bon diagrams, see my blog post from 2006 http://www.artima.com/weblogs/viewpost.jsp?thread=158340 for an example and links. Bon is the diagramming and design method for the Eiffel language.
The original Visual Design Language VDL from Solution Based Modelling and many of the SBM principles would be of a lot of interest although sadly it has dropped by the wayside as John Brugge blogs about http://jbrugge.com/blog/2007/05/10/ode-to-solution-based-modeling/ which also points to my posting http://www.artima.com/forums/flat.jsp?forum=106&thread=158300 and reading my summary of their points, I'm struck again by their anticipation of the agile principles (twenty years ago).
I've not had time to read and digest it properly but I also suspect you have some significant crossover with the DCI principles Cope espouses in his new Lean Architecture book, a good starting point for which is https://sites.google.com/a/gertrudandcope.com/www/thedciarchitecture which has a brief overview and many links.
I hope you enjoy these links as much as I've enjoyed this thread
Andy
& i thought BON was more for static relationships, than the important
and often hard to grok runtime dynamic relationships?
I have used the Dynamic Bon diagrams within UML and casual diagramming tools very successfully for documenting the dynamic aspects of an architecture. One of the nice things is their dynamic diagram shows diagrams with numbered edges between objects then pulls out the numbers into a separate textual scenario that can be read linearly.
For a given set of relationships, it is a trivial exercise to alter the numbering (if necessary) and change the wording of the scenario. Often the collaborating objects remain the same but the sequences and details of communications change in different scenarios.
This worked well for us developing an architecture for a broad spatial industry tender where the domain expert was able to continue refining the wording of the scenarios (except for the fragiility of multiple Visio diagrams pasted into Word tables!).