Communicating design
Ralf Westphal
software most efficiently and effectively communicated
a. among team members, if one part of the team changed it and another
part needs to work on the changed parts?
b. to new team members who have no/little knowledge of the overall
software system?
By "efficient" I mean quickly. How long does it take to inform
somebody about a design?
By "effectively" I mean, the person getting informed about the design
should finally have the same mental model of the design as the others,
and this mental model should mostly closely match the de facto design.
By "design" I mean overall system structure: which functional units
are there, what´s their purpose, how do they interact to realize some
user value (fulfill certain requirements, e.g. implement a feature).
-Ralf
"Kurt Häusler"
-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.
Keith Brown
Ralf Westphal
novel or an organization by putting a student in the middle of it?
"Read the novel, it's well crafted, and you'll pick up the design in
no time." or "Look carefully at the car, dissect it, and you'll know
its design."
Do I understand you correctly?
Andreas Leidig
However your concern is interesting. How do you communicate design in a formalised way?
Cheers
Andreas
Kurt Häusler
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.
Ralf Westphal
term "design" [1] for both I think its fair to compare both.
So how do you convey the design of a car, novel, house, organization?
Do you do tours through the organiszation building with a guide
pointing out highlights of the design? ("Third floor, this is where
the CIO resides. The CIO´s role is... To the left you see his secretary
´s room. The secretary is connected with the ... His task is to... He
´s dependent on...")
At least I haven´t ever seen such a tour offer. At least not as the
first choice to explain the design of an organization. Have you?
And nobody ever recommended to me to get a hammer and a crowbar to
explore the design of a house.
But as Kurt suggest, we should communicate software design by sending
people to the source. Understanding of much more complex system than a
house or car should be started at the most detailed level? That to me
sounds very strange.
[1] http://en.wikipedia.org/wiki/Design, "plan or convention for the
construction of an object or a system"
On 19 Jun., 09:22, Andreas Leidig <derlei...@web.de> wrote:
> A car is different from software. Seeing design by looking at the source would be great.
>
> However your concern is interesting. How do you communicate design in a formalised way?
>
> Cheers
> Andreas
>
Keith Brown
Ralf Westphal
> Just as you communicate the design of those manufactured products via some design tool like a blueprint, or an outline, the same applies to software. We look at >the relevant design tool, the source code. The source code isn't the finished product, which seems to where you are trying to draw a comparison, it is the blueprint >for the finished software product.
The longer I think about, though, the less important I find the
statement "Software source code is design".
Yeah, so what. It´s design with respect to machine code which gets
automatically produced by a compiler. Great. And now what?
Does this insight help us coming up with source code for solutions to
complicated problems? Don´t think so.
>
> 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,
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?
>or in the main method, of course that is no standard and it depends on the type of product, ecosystem, software design paradigm etc.
few "mountain tops" to look at (or look down from) to get an
understanding of the design of a software. Especially not for
questions like "How does the system work with regard to feature X?"
> But I have a feeling you want to suggest something even better.
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."
Is that efficient as well as effective?
To me that sounds like software archaeology.
[1] http://www.developerdotstar.com/mag/articles/reeves_design_main.html
Ron Jeffries
> 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)
Ron Jeffries
> 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
Ralf Westphal
> Hello, Ralf. On Sunday, June 19, 2011, at 11:34:58 AM, you wrote:
>
> > 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?
clean code.
>
> We work with the person to explain to them what is going on?
code or sth else.
But still: Can explaning the design be more efficient as well
effective than sitting together over heaps of code?
Ralf Westphal
> 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.
hardly of much use, I´d say.
More interestingly: Are there design ideas which in the process of
translating them into code "get lost" and cannot be easily/
unambigiously reconstructed from code?
Keith Brown
Curtis Cooley
the system and the documents begin to diverge as soon as the ink
dries. Writing pounds and pounds of formal design documents has not
yielded successful communication, or we would still have tools like
TogetherJ and Rational Rose.
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
Ralf Westphal
> A top notch dev with a strong background in design patterns could probably
> look at our codebase and grok it pretty quickly.
the visitor pattern, the flyweight pattern, the facade pattern etc.,
and MVC/MVVM is... then it´s easy to understand 30,000 or 250,000 LOC?
Because patterns are larger building blocks of software than methods
and classes? Because you wrap responsibilities with regard to the
domain (or some concern) into patterns?
> But I can flatten the
> learning curve quite a bit by simply explaining some conventions used on the
> project. "We use Commands to update domain model, and VMBuilders to query
> the domain model and produce view models for display". Now whenever she sees
> a class ending with "Command" or "VMBuilder" she's going to have a much
> better chance of understanding the role that class plays in the overall
> design.
know the design - if you know some conventions.
What I don´t understand, though, is how patterns and conventions are
tied to the problem domain. Isn´t "understanding the design" about
understanding how the problem domain is attacked?
Take a compiler for example. If you tell the new dev you´re using
commands and VMbuilders in your compiler, what does she learn about
how the task of compilation is accomplished?
Sure, any information about patterns, convention, paradigms helps.
"Communication is async", "We´re using a recurive approach to
analysis", "The UI is sending commands to the logic to start
processing" - that´s all valuable. But still... as valuable as this
information is, to me it still seems very generic.
Isn´t there any other more concrete help you can give a project
newbie? Think of some open source project you haven´t looked at. How
much would it help you to get this kind of information if you wanted
to become a contributor? What else could help?
Ralf Westphal
> My view is we "craftsmen" tend to be anti-formal documentation because
> the system and the documents begin to diverge as soon as the ink
> dries. Writing pounds and pounds of formal design documents has not
> yielded successful communication, or we would still have tools like
> TogetherJ and Rational Rose.
But what "formal" means, I don´t really know. It sounds like a threat,
an ancient bane lurking somewhere to devour the naive developer.
What´s the necessary attributes to call some form of non-code
information about a solution "formal"?
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.
(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?
> 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.
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 pretty much know what kind of introduction I´d like to get. And I
can tell you, it has little to do with code ;-) Sure, in the end there
´s code, there´s all the details. I agree with Uncle Bob: Programming
is about details. Like bridge building is about welding done right and
bolts placed right.
However, details are, well, just that: details, i.e. necessary and
unavoidable evils of a solution :-)
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 :-)
Keith Brown
know the design - if you know some conventions.<<
--
Christian Horsdal
spending time with that person going over the design at a white board
*and* in the code. Both when I'm the "old" guy and when I'm the "new"
guy, I find it most efficient and effective to go back and forth
between white board and code. The key here is the one on one
communication.
Curtis Cooley
> On 19 Jun., 23:33, Curtis Cooley <curtis.coo...@gmail.com> wrote:
>> My view is we "craftsmen" tend to be anti-formal documentation because
>> the system and the documents begin to diverge as soon as the ink
>> dries. Writing pounds and pounds of formal design documents has not
>> yielded successful communication, or we would still have tools like
>> TogetherJ and Rational Rose.
>
> I keep hearing about this aversion of "formal documentation".
> But what "formal" means, I don´t really know. It sounds like a threat,
> an ancient bane lurking somewhere to devour the naive developer.
> What´s the necessary attributes to call some form of non-code
> information about a solution "formal"?
>
that "models" the system and you want to keep around by say checking
into your SCM.
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?
David Starr
Curtis Cooley
need better documentation ;)
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.
Curtis Cooley
> I may get a little flame for this, but I have to mention it.
> 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.
> David Starr
> pluralsight.com | elegantcode.com | @elegantcoder
>
>
>
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.
Vlad Dumitrescu
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.
Ralf Westphal
> 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.
Correct?
Ralf Westphal
> Formal documentation simply means any non-executable documentation
> that "models" the system and you want to keep around by say checking
> into your SCM.
That means, if any other form of documentation could be generated from
code, it would be ok to use it?
Or if there was combination of model diagram and process that would
lead to code being in sync with the model diagram, it would be ok to
use?
> 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.
But I´d say, working code for the next 8 years is even better than
working code now.
>
> 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.
I just don´t believe that any other form of design document than
source code needs to get out of sync or needs to be of quickly
deteriorating value.
Agility was right to criticize the documentation practice before it.
To much paper was produced.
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.
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.
(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.)
So what can we do? Is TDD gonna save the world? I doubt it. It´s "peep
hole software development" ;-) 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.
>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?
non-functional requirements. It needs to be correct and do the
required job. Sure. But that´s easy to show. Ask a customer and there
is hardly any doubt if you hit the mark.
Much more important is the question if the whole code system will
evolve over time. And that´s not gonna be answered by any code by
executing it.
Take a piece of open source code and check if it´s wrong. Takes you a
minute. Just run the tests.
But how long does it take you to assess its evolvability?
Matteo Vaccari
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.
Matteo Vaccari
> > Just as you communicate the design of those manufactured products via
> some design tool like a blueprint, or an outline, the same applies to
> software. We look at >the relevant design tool, the source code. The source
> code isn't the finished product, which seems to where you are trying to draw
> a comparison, it is the blueprint >for the finished software product.
>
> This has been said by Reeves [1] and has been discussed much.
> The longer I think about, though, the less important I find the
> statement "Software source code is design".
> Yeah, so what. It´s design with respect to machine code which gets
> automatically produced by a compiler. Great. And now what?
> Does this insight help us coming up with source code for solutions to
> complicated problems? Don´t think so.
>
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
Ron Jeffries
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.
Curtis Cooley
wrote: some really cool thoughts that I did not want to make people
scroll through, but I wanted to reply to his post because it's what
made me think about what I'm about to write about.
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?
Raoul Duke
> 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 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.
Ron Jeffries
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.
Ron Jeffries
> 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
Ralf Westphal
> Hello, Ralf.
>
> 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 ...
I´m a bit incredulous, then that´s right ;-)
I have become incredulous. After many years not caring for more than
textual source code I´ve come to the conclusion it´s not enough, if we
want to work on software collaboratively, efficiently and effectively.
That´s my personal conclusion after 30 years in the business years of
assembler programming, Pascal, C, C++, VB, 4GL, and C#.
It´s not that "just source code" (or "mainly focus on source code")
does not work. It works, it even has benefits over "formal docs
first".
But that´s like saying Fortran has benefits over assembler :-) It´s
not the end, it´s just a start.
It´s an important insight how little "formal docs" help for software
(compared to maybe electrical engineering).
However, I can´t believe we as an industry would want to rest on that.
We want to deal with the most complicated "machines" in a way medieval
masons dealt with static things like houses or even cathedrals?
This is not to say I´m against collective code ownership, pair
programming, TDD or the like. That´s all great and well.
Is that it, though? We´ve reached the pinnacle of software development
methodology? "Read the code, let and expert guide you through it. Use
TDD to find the right structure for the code. Don´t think for long, don
´t use diagrams for more than a very temporary sketch, then sit down
and code." That´s it?
I believe we can do better.
The reason: Our brains are made for more than reading. To build a
mental model from text is almost the hardest way to go. Simple
example: Would you prefer a map or a spoken description for finding
your way across an unknown city?
At least I never print out the Google Maps route description, just the
map with the line showing my way from A to B.
Again: I understand how frustrating it is to look at a diagram (map)
and later find out it was not telling the truth about the code
(terrain). To rather explore the terrain myself or to rely on a scout
to guide me through unknown terrain is a natural reaction. Exploration
of the real thing surely leads to deep knowledge.
But is that the most efficient way of getting acquaintant with some
terrain? At least not for me. I love Google Maps including Street
View. I can zoom in and out as I like before or after actually
visiting a place.
Script was a huge invention. Translating spoken words into a durable
form that can even be copied. Great!
However, I´d argue that Symbols are an equally huge invention.
Translating mental models into a durable form.
And I would like to think we both agree on that - the main difference
between our points of view being the meaning of "symbols getting out
of sync with the symbolized".
I understand you say, "Since any symbolizations are not the real thing
they are of limited/temporary value only. The truth is in the
symbolized only. Therefore we should focus our work on the
symbolized."
And I´m saying: "If syncing is a problem, then let´s solve it.
Symbolization is so powerful we don´t want to relegate it to some
occaissonal and optional use."
What do you think?
> 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.
it the same in all heads. And it needs to match reality.
Model mismatch is a huge impediment. And as long as mental models are
just that, it´s more likely they are different.
>
> 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.
That´s why the translation effort (from head to code, from code to
head) should be minimized. It should be made as easy as possible.
Build a mental model from code is more difficult than build it from a
picture.
Take a FSM for example. Would you prefer a diagram or a table or code
to understand how a software reacts to events?
>
> 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.
The question is, though, what to make of that? :-)
Rest with the source code - or strive to "enrich" the source code so
that helpful diagrams and textual source code don´t get out of sync
anymore?
(Generating a class diagram from source code is a start, I´d say. But
they are not very informative in terms of how a software system
actually works. Sequence diagrams generated from source code also
help. But for "entering a system" they are mostly too fine grained.)
>
> 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.
crucial details. Like a fallen tree blocking my way in the mountains.
It´s not on the map, but has a big impact on me.
Does that make the map useless? No. I´d be a foul to make a trip to
the mountains without a map. It can even help me deal with the fallen
tree.
>
> 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.
Please take it that I understand this argument.
It just leads me to a different conclusion.
>
> 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.
not.
Assumption #1: Any description of a design necessarily gets out of
sync with reality.
Assumption #2: Experts are readily on hand whenever I need them to get
into and around a software system.
Assumption #3: The "absolute truth" of source code is so important it
outweights any other concern.
If "source code first" had no drawback, I´d be all for it.
But there are quite some, e.g.
a. depending on my informational needs source code contains noise
(irrelvant detail)
b. building "mental pictures" from text is harder than building them
from pictures (it takes longer, it is more error prone)
c. repeatedly recreating temporary pictures from source code is
inefficient (strange for an industry so focused on reuse ;-)
> 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.
built the empire state building! The truth of the design is in the
building."
>
> 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.
baking recipe or a process diagram.
> That's the essential truth of the art: it is how we must do it.
look further? We´re at the pinnacle?
> We are unlikely to create a perfect design in our head or on
> paper:
perfect design?
> 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.
designing through coding takes too long."
> 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.
dimensional textual representations of a design and the actual
multidimensional reality of a design.
Text, especially formal language text, is so limited in its
expressiveness. What takes just two circles and an arrow on paper
might end up as a whole page of text or more. Add some color to the
diagram to maybe express different threads and you need to add more
text in the same dimension whereas the diagram essential became 3D.
Does nobody except me feel the pain the "dehydration" of text into
multi dimensional mental (visual) models causes?
If you emphasize the importance of broad bandwidth communication
between humans to efficiently and effectively develop software, why
are you content with a one dimensional representation of the rich
multi dimensional models created by such communication?
>
> Not really. I find myself wishing you were trying more actively to
> understand what we are saying.
Ralf Westphal
> 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.
code that´s readable, too.
But there is another conclusion that can be drawn from the above: Don
´t focus that much on code.
I´d even say: Code is necessary evil. Avoid writing code at all costs.
It´s the hardest part of software to change.
So whenever possible use other means to form a solution. And make
writing code as easy as possible.
> 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.
´re describing a current state.
As philosophy has taught us, though, we cannot derive from what is how
it should be.
You developed a coping strategy and did not change the world.
I for one don´t want to be content with such a state of the world,
though.
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.
If I want to help people cross a river, a bridge is needed. But does
that require me to like to fiddle with stone and mortar? No. Somebody
needs to be able to work with those materials. If that´s me, well,
then I better know how to do it, but I don´t need to like it at every
moment. And of course I´ll try to make building the bridge as easy as
possible - maybe by replacing stone and mortar with steel.
I´d say: In the name of Kaizen stay sensitive to pain any method/
technology causes you. Don´t assume you have reached the pinnacle;
very likely it´s just some hill top, a local optimum.
Christian Horsdal
> anyone explain why it's not a good idea to read code and master
> reading code?
reading the code gives a very, very detailed view of the system.
Sometimes it's sort of like trying to figure out the layout a building
by standing 2 millimeters from the wall and staring at. To understand
the overall structure of a system we need to be able to step back, and
look at, say package structure, layers and so on. We also need to look
at the dynamics of the system, not only the static structure: For
instance which processes/threads/actors/etc are there and how do they
interact? And how are they distributed in the production environment?
These things aren't usually obvious from the details of the code.
Having said that I do agree that we can and should strive to make as
many of these "overall" things visible in the code as we can, and that
we should embrace reading code. The devil is in the detail after all.
/Christian Horsdal
horsdal.blogspot.com
@chr_horsdal
Ron Jeffries
wrote:
> 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
Raoul Duke
> Maybe, in all seriousness, you just don't like programming?
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.
Curtis Cooley
> Hello, Ralf. On Wednesday, June 22, 2011, at 3:24:33 AM, you
> wrote:
>
>> be forced to stare at source code. I don愒 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?
>
disconnect between Ralf and myself. He hates code, me not so much, so
I guess our goals are different. I don't mind learning a system by
reading the code, and I feel I'm pretty good at getting up to speed
fast enough to contribute that way.
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.
Ralf Westphal
> Hello, Ralf. On Wednesday, June 22, 2011, at 3:24:33 AM, you
> wrote:
>
> > 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?
As a customer, what can I expect from people who like programming?
I guess, the least I can expect is, these people will always find ways
to do what they like.
They´ll have more or less subtle means to increase the amount of time
they can spent doing it.
That´s why I as a customer essentially should not trust them beyond a
certain point to spend my money wisely.
This is especially frustrating since I as a customer have no clue what
those programmer guys are doing in the first place. There´s no
tangible product coming out from all this programming.
Sure, this is not what you want to hear, and you certainly don´t
agree, Ron. But since your question is unnecessarily personal and
comes with so many assumptions, I feel it justified to answer like
this.
Programming is a tool. Nothing more. And it might be the case that
people who like to use a tool use it in a more efficient and more
effective way than people who are neutral to it. Maybe. And I really
mean maybe, because isn´t it a trait of professionalism to do things
right even though you don´t like/love them? If I see a physician I
require of him a professional treatment even though he does not like
me or at the very moment would prefer to be at a lake fishing because
he hasn´t had a vacation in three years.
Just to make a point and to completely drive you off ;-) let me say:
Passion is overrated.
Or let me turn your question around in another way:
So you like programming? Then let me ask you how you ensure you
advance your skills or the art? If all´s nice and well and does not
cause you pain then I don´t see there´s much motivation for you to
change. If programming the way you do it does not cause you any pain,
then you´re content; there´s no difference between how you do things
and a vision of how you´d like to do them because it´s even easier
(causing less pain). That pretty much sounds like a standstill.
Should we assume Ron Jeffries to like programming so much he´s
essentially become a tired conservative programmer who would like to
not be disturbed in the ways he´s programming?
I guess not.
So if you want to discuss stuff seriously with me, please try to
attack my arguments, not my likings.
Ralf Westphal
> > Maybe, in all seriousness, you just don't like programming?
>
> 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"
So what´s "programming"?
Where does it start, where does it end? What are "programming
activities"?
What´s its purpose?
What´s the difference between "programming" and "software
development"?
Why is this forum about "Software craftsmanship" and not "Programmer
craftsmanship"?
> 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.
before you define it you can´t really tell if it is good or bad.
Ralf Westphal
> Funny, I was thinking the same thing, but it's revealed a huge
> disconnect between Ralf and myself. He hates code, me not so much, so
publications over the past 13 year´s you´d know.
But that does not mean I love each and every coding task and each and
every line of code.
Not every minute spent coding creates a feeling of joy in me.
I feel pain in coding. And I wonder if you don´t.
Passionate people are sensitive people. Since I guess you´re
passionate about coding, I assume you feel it too.
It was a pain to write in C#
MyClass x = new MyClass(...);
So I felt relief when type inference was introduced:
var x = new MyClass(...);
It was a pain to need to define explicit delegate types in C#, so
lambda expressions are a pain reliever
It was a pain to do memory management by hand, so GC is a pain
reliever.
It is a pain to "reverse engineer" source code to get a bigger picture
of software design.
How can we relieve the situation?
> Generating source code from high level diagrams though, which is where
> I assume Ralf is going?
I don´t believe in CASE or MDA.
But that does not mean we cannot benefit from DSLs in some way.
And it also does not mean we cannot benefit from more explicit
modelling.
It´s the right balance we should be looking for.
>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.
We´re living in times where you can decompile executable code, where
that´s even a tool everybody wants to have. (At least it´s all the
rage in the .NET world with several competing offerings.)
So why shouldn´t we try to embed even more high level info in code?
Why can´t I re-regenrate useful bigger pictures from code? (No, I don
´t mean class diagrams, because class diagrams are not models.)
>
> 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.
generation.
But that´s not my assumption.
>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.
Maybe we can say, CASE and even UML flopped. But does that mean the
basic idea of helping programmers to understand software better with
diagrams is not viable? Should we give up on designing in a brain
friendly and collaborative way just because the tools of the past were
not good enough?
>
> 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.
I at least don´t think so. And my experience within the past 15 months
leads me to believe, this is not futile.
There is a saying, that all problems in programming can be solved by
another level of indirection.
Let me paraphrase that: All problems in programming can be solved by
another layer of metadata.
First we programmed in assembler/machine code.
Then we programmed in Fortran, C, C++ which got compiled into machine
code. That was a one way street.
Then we programmed in Java, C# which got compiled into some byte code.
But with the help of reflection APIs we were able to regenerate the
source code. To speak with Jack Reeves: We were able to reverse-design
software automatically.
Why not extrapolate this?
In the future we´ll be programming in a way, where our designs and
source code get compiled into some executable code. But with the help
of some reflection API we´ll be able to not only regenerate the source
code from that, but also rich design documents on different levels of
abstraction above the source code.
Source code and "design documents" will be in sync and will be
complementary.
That´s my vision, because 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.
Arnaud Bailly
I have been following this thread with a lot of interest. I feel definitely close to Ralf's position: There has to be a better way, there has to be something different. I do *love* coding and I am really passionate at it. I tend to think that coding is very close to writing up to and including its artistic and stylistic aspects. I have been involved in the past few years in much legacy code and, while there is some archeological joy in it, I felt it more and more painful to deal with all this crappy piles of classes, methods, functions, XML descriptors, properties files, maven projects, thousand of files... I mean, I sometimes feel close to physical sickness: It disgusts me, it is a painful weight to bear that I feel physically in my aching back from tension. And the thought that most infuriates me is that when I am actually writing code I do just add more noise.
I totally agree with Ralf when he feels somehow inadequate that the only way to convey efficiently the design (hence the meaning) of a software program is through personal interaction with someone already knowledgeable about it. It feels like wiping out several thousand years of written speech civilization and several hundred years of printing. And while there is value, and joy, and great moments of complicity, and the warm feeling of shared understanding and participation in a common event, and the possibility of transmitting intangible and implicit meanings in oral communication, it is not anymore the only way to communicate between people in our world. It is not even the main way of communicating (what are we just doing right now, exchanging mails across several oceans?). Sure, I would love to hear the Illiades declaimed by an aedes, but I can also read, and understand it. And through this reading, I can feel all the heroism, the inner conflicts, the tragedy of this war. And can have a glimpse of what it meant to be a greek warrior king around 1000AD and more importantly and can use that knowledge in my modern world to fortify my moral self.
I would like to offer this (not really new nor groundbreaking) idea: What if the inadequacy we feel (or at least some of us feel) was mostly related to the inadequacy of the languages we are using? And by language I mean not only and not mainly the programming languages we use (this is not a PL flame war) but the way we use it?
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.
Remark that 1. and 2. are tied in a self-reinforcing loop (think C++...). This explains why I am interested in some of the promises of software craftsmanship: Cooperating to produce not only cleaner but more understandable, more interesting code.
So what we might really need is a) an improvement in languages and their environments in order to allow coders to write at different abstraction levels easily and b) a continuous effort, supported by crafstmanship practices like peer reviews/programming, TDD, SOLID programming and the like, to improve our ability to *write* but also to *read* code. This list is mostly dedicated to b) I think and there quite a few people working on a), especially in the PL and SLE academic communities, so there is hope, yet we are far from harvesting benefits from all these efforts in our day-to-day work.
My 50 cents,
Arnaud
Ron Jeffries
wrote:
> 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.
Curtis Cooley
> Why not extrapolate this?
>
> In the future we´ll be programming in a way, where our designs and
> source code get compiled into some executable code. But with the help
> of some reflection API we´ll be able to not only regenerate the source
> code from that, but also rich design documents on different levels of
> abstraction above the source code.
>
> Source code and "design documents" will be in sync and will be
> complementary.
>
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.
Ralf Westphal
> in much legacy code and, while there is some archeological joy in it, I felt
> it more and more painful to deal with all this crappy piles of classes,
> methods, functions, XML descriptors, properties files, maven projects,
> thousand of files... I mean, I sometimes feel close to physical sickness:
> I totally agree with Ralf when he feels somehow inadequate that the only way
> to convey efficiently the design (hence the meaning) of a software program
> is through personal interaction with someone already knowledgeable about it.
supporting my view that we should think about additional ways to
efficiently and effectively transmit design.
> It feels like wiping out several thousand years of written speech
> civilization and several hundred years of printing. And while there is
> value, and joy, and great moments of complicity, and the warm feeling of
> shared understanding and participation in a common event, and the
> possibility of transmitting intangible and implicit meanings in oral
> communication, it is not anymore the only way to communicate between people
> in our world.
Very true.
>It is not even the main way of communicating (what are we just
> doing right now, exchanging mails across several oceans?). Sure, I would
> love to hear the Illiades declaimed by an aedes, but I can also read, and
> understand it.
http://1.bp.blogspot.com/_PixsqLu0qdA/STlpVapAMuI/AAAAAAAAAW0/H7_a7ifKLkY/s320/iliad39.jpg
http://farm3.static.flickr.com/2142/5713327860_343860bd1e.jpg
http://www.oxfordtutorials.com/AchilleShield.jpg
As much as personal interaction can accelerate understanding - it also
can impede it.
Why should I be limited to the speed of someone explaining me
something? I can read much faster than anybody can speak. And I can
take in with a single look more than by listening for 5 minutes.
> 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.
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.
Ralf Westphal
> 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.
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?
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 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.
Curtis Cooley
> On 23 Jun., 17:31, Curtis Cooley <curtis.coo...@gmail.com> wrote:
>> 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.
>
> If you agreed with me all along, and if such a tool does not exist...
> why aren´t you trying to improve the situation?
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.
Andreas Leidig
Am 24.06.2011 um 18:16 schrieb Ralf Westphal:
> 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
Ron Jeffries
> 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
Arnaud Bailly
> 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.
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.
Furthermore, there is a lot of *meaning* which is extremely contextual, and this is inherent to human language and thought: Meaning is more the by product of relationship than an attribute of things, more relational than essential, so it is no surprise it is easier to build it from discussion and whiteboards session than from solitary reading. Yet it is clearly a limitation of our current tools that *so much* of the meaning need to be contextual.
Regards,
Arnaud
Jason Catena
incapable of grand abstraction is if you equate all source code to
assembly language. We´re past that with compilers. All the higher
languages raise the level of the conversation, and put great machines
at our disposal (DSLs continually raise the bar and simplify the text
we need write; the entire apparatus of the internet hidden behind
socket()) or hide them (garbage collection; the forest of duplicated
data behind referentially-transparent data types). Saying we haven´t
progressed in programming because we don´t program in pictures is as
narrow-sighted as saying A.I. is a complete failure because machines
are not conscious, while they beat us at chess and Jeopardy and
monitor camera feeds for unusual events in real time.
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
Arnaud Bailly
I am really glad you agree with me! This is exactly what I wanted to say, and I had in mind the likes of Haskell as model of languages in which varying level of abstractions are possible.
When I say "improve our textual representations, possibly allowing more dimensions to be used than simple linear text", please note the *possibly*. Text is syntactically linear: It is the job of a parser to transform a stream of tokens into an AST, whether this parser is a human being or a machine. But of course, it is semantically much more complex, with the semantics of the language being a stack of transformations. This is true of machine and human languages, by the way (in one of its books on linguistics, Noam Chomsky which invented the concept of formal languages and the famous Chomsky hierarchy explains how the languages embed at least two levels of grammar thus allowing people to understand sentences that they had never heard or read).
My point is:
1. Following Ralf, I am not happy with the current situation where the *only* effective way to communicate the higher level of abstractions and meanings of software (whether you call this architecture or design or domain knowledge) appears to be through face-to-face communication and oral transmission,
2. But I do not follow him in is desire for more pictures and diagrammatic representations,
3. I follow Uncle Bob when he says that MDA/MDE/MDx has failed although we "all" believed in its promises in the 90s and what is remaining is, well, programming language,
4. But I do not follow him (nor Ron) when he says that "Programmers are detail managers". Maybe they are today, but this is not what I am looking. Of course, no matter of MDx will remove the fact that running a software, in the end, means changing the state of some insanely complex electronic circuitry (remember Church-Turing?) and we will have to pay attention, at one time, to these details. But nevertheless, we need to be able to abstract away those details. While it is true that all abstractions leak, it is also true that we need more abstractions.
5. hence I believe there is still a lot to be discovered and improved in textual languages (adding more syntactic dimensions is one possibility). Interestingly, the academic community around software language engineering (SLE2011 conference is due beginning of July in Braga, Portugal and is attracting a wide array of diverse people) is really gaining a lot of attentions those days while the models' guys are not anymore in the forefront, even if there exists interesting tools and concepts to draw from them.
Without fear of being pedantic, I would like to point you to a favorite author of mine, Jorge L. Borges, and particularly to one of its short stories "Funes or the memory" in which a young man, Ireneo Funes, is cursed with the ability to remember *everything* he has ever seen or lived. Funes is an anti-metaphor of the way we think: By generalizing, by abstracting details. And he dies under the weight of all these details....
Best regards,
Arnaud
PS: And I too think category theory will save the world.
> Regards,
> Arnaud
Ralf Westphal
> 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.
Right to the contrary: almost anything drawn on a whiteboard is
helpful to understand a solution.
In fact I´m a big fan of whiteboard sessions; do them all the time and
suggest to replace the whiteboard with a Visual Presenter like this
one: http://www.samsungpresenterusa.com/products/productdetails.asp?ProductID=21
> Seems to me those developers are addressing their pain points. Writing
> SQl in code was painful and error prone, so we developed ORM.
And to reduce the amount of code needed is good.
In the end, though, I haven´t seen any project being saved from
maintenance problems by an ORM.
Even to the contrary: ORMs have led many teams to high coupling of
code.
Ralf Westphal
> Most programmer do not design they do programs. If a tool would exist to show the design the tool would simply implode. :)
source :-)
>
> 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.
the design is easily visible in the code.
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.
We can be happy if the text captures all the nuances of our mental
models in some way. But to expect from it to display them in a rich
way is too much.
Compare the number of people reading to the number of people watching
TV.
What do most people prefer if you told them "Here´s a description of
an event, and here´s a video of the same event. Which medium do you
want to use to make yourself acquaintant with the event?"
Why is http://www.screenr.com/ such a success?
Why is "Presentation Zen" such a success? (http://
www.presentationzen.com/)
Because written descriptions are overrated for many purposes.
>
> Let's find an easy way to give people the ability to express what they mean.
solution on different levels of abstraction and in a way to easily
convey it to others and in a way this "model" does not get out of sync
with code.
Ralf Westphal
> Here's a snippet from Bob Martin's new book, The Clean Coder, that
> seems to me to bear on this discussion:
I even agree that programming is about detail. Getting the details
wrong can lead to disasters.
But what´s not about detail? Movie making is about details, being in a
SWAT operation is about details, doing a heart transplant is about
details. And if you ask a shoemaker, shoemaking is about details, too.
So saying, programming was about details is a pretty general
statement, I´d say. So general even, it´s almost useless.
In addition: details are relative.
Look at the earth from space and the chinese wall is a detail. Stand
right in front of it and it´s not a detail anymore, but the individual
stones it´s made of are details.
What´s a detail and what´s not is a matter of perspective. Yes, in the
end every stone of the chinese wall was necessary to build it. But do
you think the architects and and master builders of the chinese wall
cared about individual stones?
If I´m the one to program a sorting algorithm I better care about
array boundaries. They are an important detail then.
But if I´m thinking about how to realize a feature like "Display the
selected books in ascending order according to their purchase date" I
sure as hell don´t even want to care about such a detail.
Programming is as much about abstraction as it is about detail.
Otherwise we´d not be using Java, C#, RegEx, SQL, ORMs etc.
I´m sorry to say, but I would not want to hire a programmer not being
able to switch the level of abstraction he´s thinking on.
>
> 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.
of years.
But as the history of programming is a history of rising levels of
abstraction I predict, we´ll not move forward the industry a lot as
long as we´re fixed to the level of abstraction languages like Java or
Clojure are offering. And I don´t mean lambdas or monads or whatever
technological minutiae. I mean how we can express our solutions on
different levels of abstraction: from coarse grained to finely
grained.
What a deplorable sight it would be to look at state-of-the-art
software development in 2025 and still see people just using
whiteboards and some beefed up version of vi (like VS or Eclipse).
Ralf Westphal
> The only way you can say that source code text is one-dimensional and
> incapable of grand abstraction is if you equate all source code to
> assembly language.
Java, C#, Clojure, Ruby source code is just text.
And text is just a string of characters which means it´s just a one
dimensional shape (a line).
Wrapping lines and indenting text does not make much of a difference.
You still need to scan text from left to right and top to bottom to
understand it. (At least where a latin alphabet is used as in
programming languages.)
Look at this picture:
http://upload.wikimedia.org/wikipedia/commons/thumb/b/b9/Farbkreis_Itten_1961.svg/220px-Farbkreis_Itten_1961.svg.png
And then write up a text describing it.
What do you think I´d prefer as a recipient?
(At least as long as you´re not a literary author like Hemingway or
the like ;-)
> We´re past that with compilers. All the higher
> languages raise the level of the conversation, and put great machines
> at our disposal (DSLs continually raise the bar and simplify the text
> we need write; the entire apparatus of the internet hidden behind
Except: I don´t believe many developers will be able to come up with
their own DSL.
Some problem domains benefit from a specific DSL. But mostly what we
need is general purpose DSLs like SQL or RegEx.
> 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,
universal - but hard to do.
So why should I use atoms (or molecules) to build sth if I have stones
or screws?
> we´d be programming in pictures, since it´s not hard to write a
Have you ever compared 4 MB of MSBuild (or (N)Ant) script with a
FinalBuilder script with the same functionality?
What´s easier to understand?
What´s easier to produce by someone not a MSBuild/Ant buff?
> 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.
example I´d never want to write a math expression in a graphical
language. At least not the simple expressions I have been exposed to
in high school.
Also I´m no fan of flow-charts which try do bring imperative
programming to the diagram world.
There is a line I would not cross. On one side of the line there´s
stuff to be expressed beneficially as text. But on the other side is
stuff which can be expressed as text, but what then is hard to read/
understand.
Take this for example: http://www.di-arezzo.de/multimedia/images/boileau/part/b3310.jpg
Or take this for example:
http://www.enigmatic-consulting.com/Communications_articles/EnMnofields/ENMimages/Wire_inductance_integral.gif
Or this: http://www.mathematik.uni-kl.de/~pfister/ballzeitung/pics/TwoStage.gif
All this can be expressed as text. But no one would claim the textual
representation should be studied instead of the rich graphical
representation.
Or when was the last time you studied a LaTex file instead of the
printed form? All formatting is present in the LaTex file - but still
you prefer a graphical representation before your eyes.
Why don´t you for rich mental models? Why do you (do most of those
arguing here with me) prefer textual representations?
Sorry, there´s only one reason I keep hearing: because there is a real
danger that any other presentation will get out of sync with source
code.
And I full well understand that. Yes, that´s a real danger.
So what? Let´s look it in the eye and find ways to overcome it. There
are enough DI containers, ORMs, ESBs... we should direct our
programming power to other problems bugging software development in
general.
Vlad Dumitrescu
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
Ralf Westphal
> 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.
What about runtime?
There are tracing frameworks (from log4net to Gibraltar and
DynaTrace). But is that enough?
Are the design time abstractions still present in the data compiled at
runtime?
And if so up to which abstraction level?
Ayende just wrote about the importance of "debug hooks",
http://ayende.com/blog/21505/where-are-your-debug-hooks.
But I think this only touches the real issue: we want to be able to
monitor and steer applications at runtime if necessary. We want to
wire tap into them. Maybe we even want to run them in slow motion to
watch what´s happening?
> 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?
complexity.
But how do we arrive at trust? By looking at the source code? I guess
not.
At least I don´t have time for that. I need to solve my clients
problems, not check on 3rd party code.
So for sure I´ll not use open source software to look at its source.
But maybe others look at the source and vouch for it? Then trust can
be build via a chain.
Vlad Dumitrescu
>> 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?
>
> Yes, I guess we have to trust other code. Trust is a means to reduce
> complexity.
> But how do we arrive at trust? By looking at the source code? I guess
> not.
> At least I don´t have time for that. I need to solve my clients
> problems, not check on 3rd party code.
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
Jason Catena
Vlad Dumitrescu
> On Sat, Jun 25, 2011 at 16:07, Vlad Dumitrescu <vlad...@gmail.com> wrote:
>> 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.
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
Ron Jeffries
> 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
Vlad Dumitrescu
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
Raoul Duke
> express the interface by example and, through being executable,
> provide a concrete assurance that teams' new versions did not break
> the system.
except for all those ways in which tests can't prove that ;-)
Ron Jeffries
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
Ralf Westphal
> 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).
You can´t understand a large code base in all details.
Some parts you will know by heart and build a very current mental
model from the very details.
But other parts you need to understand, too, but it´s sufficient to
know how they work on a higher level of abstraction.
This mental model you obviously cannot build from source code.
So how do you do it? By getting it explained again and again by other
people?
How time consuming.
Written word and "printed" diagrams have already been invented :-)
Currentness is only one value out of many.
Independence of development is another one.
Also abstractions tend to change at different speed. The higher level
the abstraction the lower the change frequency.
Code has the highest change frequency; it´s the lowest level of
abstraction; it´s absolute detail.
Still, though, if diagrams on higher levels of abstraction could be
generated from source code, that would be better than have them
separate.
> 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.
means it has been decomposed into subsystems hidden behind explicit
and separate contracts. Bounded contexts, application partitions, OS
processes, components to me are essential for modularizing a software
system. They can be treated as units of distinct functionality, and as
black boxes on different levels of abstraction.
Ralf Westphal
> 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.
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?
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."
>
> possible - and beyond that invent your own style. Just keep talking at
> the whiteboard."
>
> Is that what you´re saying?
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
Ron Jeffries
> 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
Raoul Duke
> 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.
hmm, ok, i'll definitely take that as serious food for thought.
thanks,
Ralf Westphal
> and playing a music instrument. The most important educational
> activity is the student’s doing the relevant things under suitable
> supervision and guidance.
I´d even say: Nobody can teach anybody anything :-)
The learner can only learn by himself.
But of course there are different means and media to learn with and
by.
Learning by doing is important. Learning by doing and getting sound
feedback not only from a machine but also from experts is even better.
Learning by reading, thinking through, discussing is also not to be
neglected.
Another question: What is to be done to learn? Is just coding doing? I
doubt it.
Doing is the application of any knowledge. So I´d say learning by
doing does also apply for designing software not only by coding :-)
Which might be a skill not equally spread as other skills :-)
Ralf Westphal
> 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.
Because I think, when look closer at my comments here you´ll see that I
´m not rejecting TDD per se.
I´m just trying to instill some sensivitivy to whatever signals there
might be hinting at limitations of TDD.
To believe "OO is it" or "TDD is it" or "Scrum is it", to me, is the
first step into dogma.
Which I hope we can agree on is bad in any case.
There is no silverbullet? Great.
There should be no dogma.
I fully acknowledge what you and others are saying about TDD: "It
works for me."
That´s great.
What I know hear, though, is openess for a different view of the
programming world where TDD does not work for me (and others). It´s
not good enough. I feel pain.
To answer that by suggesting people who think differently are either
not passionate about programming or are just plain less skilled, well,
is not very polite and in the end does not really further the
profession, I´d say.
I keep hearing "It works for me."
Then I´m presenting arguments why there are limitations to what
"reading the source" can offer.
Unfortunately hardly any of my arguments have been taken up by you or
others to actually discuss them (not just discount them).
For example the fundamental argument of text being a poor
representation of almost anything. Text has its benefits, sure. But it
´s so much harder to understand than more "natural representations" of
music, math, electrical circuits, bridges and whatnot.
Any design can be codified as text. But except for programmers no
other craftsman (or engineer or musician) would recommend the textual
version over a more rich graphical/multi-dimensional version.
This unwillingness to actually discuss TDD (or any other practice) in
a critical manner is what frustrates me most.
So, please, don´t blame me for per de rejection of TDD. That´s not,
repeat: not, my point of view.
> What positive, actionable recommendations would you offer, and how
> would you blend them in with other things like TDD?
described on hundreds of pages by me and others.
Here´s a link to the current page of resources:
http://clean-code-advisors.com/ressourcen/flow-design-ressourcen
Unfortunately, the description/discussion so far mostly has been in
German.
You´re saying "TDD works for me".
I´m saying, "TDD is not enough". It works for me on a small scale; but
on a larger scale it´s too slow, and does not support collaborative
software development enough.
You sure understand I cannot condense an outlook on software and
approach to designing it into a short posting here. But here are some
benefits I feel coming from what I and others are doing:
* From the requirements I read I can derive the design of my solution
at a high level.
* The design is natural and intuitive in so far as it does not
speculate about code entities, but by using the domain language "tells
a story" about how the software is going to work, how required feature
will come together from behavior on different levels of abstraction.
* The design easy to do and to comprehend because it has as many
levels of abstraction as deemed appropriate.
* It´s easy to do the design either alone or with a group of
developers. Just a small symbolic vocabulary is needed.
* The design is just design and not coding because it does not try to
replicate what programming languages do well.
* The design "automatically" follows fundamental principles like
"loose coupling", SRP, SoC; and it deals explicitly with different
kinds of dependencies and mitigates their negative effects.
* The design is visual which allows for quick communication.
* The design can be translated losslessly into code; it also can be
regenerated from code.
* By being visual the design makes it easy to spot places where to
apply change.
* The design makes it easy to switch from sync to asny programming,
from local to remote, from single dev to team.
* Since the most important functional units of a design, the
operations (leafs in the tree of abstractions), are independent of
each other, it´s easy to test them.
* Operations are usually so small, they can be code quickly. Using TDD
to do that is recommended.
The approach is orthogonal to (almost any) programming platform and
other techniques like pair programming, TDD, or Scrum.
It´s not to oppose what works for others but to show what could even
work better by exploiting simple psychological facts, e.g. structures
are easier to communicate/understand in a visual way or abstraction is
an important tool to cope with complicatedness or diagrams and product
need to match 100%.
The whole thing is called Flow-Design and Event-Based Components and
is based on several approaches in existence since the 1970s like Flow-
Based Programming, Unix Pipes, Event-Driven Architecture, CEP, Event-
Based Programming etc.
But FD/EBC also contains facetts of DDD plus TDD and is trying to
cover more ground. It´s guiding the developer from requirement
analysis to code.
This all will sure not deter you from what works for you. May you say,
this is all insubstantial. And that´s fine.
But maybe others are feeling more pain when approaching design just
with TDD in hand as a tool. Like dozens of people I meet each year. It
´s those developers I would like to offer an approach to try out, if
it works for them as it works for me.
Let me again invite you and others to do one of the AppKatas here:
http://bit.ly/ixmFet
And feel for yourself, how easy (or difficult) it is to find a design
and write evolvable code and communicate what you´ve done.
And then share the outcome to discuss.
Andreas Leidig
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
Keith Brown
Torbjörn Gyllebring
Curtis Cooley
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
philip schwarz
Here are some ideas from the Pragmatic Programmer's "Pragmatic
Thinking and Learning":
########################################
There are two cognitive modes: L-mode and R-mode. L-mode (L for
linear) gives you these abilities:
Verbal: using words to name, describe define
Analytic: figuring things out step-by-step and part-by-part
Symbolic: using a symbol to stand for something
Abstract: taking out a small bit of information and using it to
represent the whole thing
Temporal: keeping track of time and sequencing one thing after another
Rational: drawing conclusions based on reason and facts
Digital: using numbers as in counting
Logical: drawing conclusions based on logic (theorems, well stated
arguments)
Linear: thinking in terms of linked ideas, one though directly
following another, often leading to a convergent conclusion
R-mode (R for rich) gives you these abilities:
Non-verbal
Synthetic
Concrete
Analogic
Non-rational
Spatial
Intuitive
Holistic
We have a bit of a cultural bias toward L-mode thinking and related
activities.
Although the analytical and verbal capabilities of L-mode thinking
have brought us (humanity) this far, we've lost some key capabilities
from an overreliance on L-mode at the expense of R-mode. To progress
in order to move on to the next revolution in human development, we
need to learn to reintegrate our largely neglected R-mode processing
with L-mode.
Both L-mode and R-mode have their separate approaches to pattern
matching. R-mode sees the forest; L-mode sees the trees. E.g. in the
following diagram, L-mode sees lots of instances of the letter 'I',
whereas the R-mode sees a big instance of the letter 'H'.
I I
I I
I I
I I
IIIIIII
I I
I I
I I
I I
The L-mode is a symbolic machine; it rushes in quickly to provide a
symbolic representation for some sensory input. That's great for
symbolic activities such as reading and writing but is not appropriate
for other activities.
########################################
Maybe the reason why some may favour code over diagrams is that they
have a bias toward L-mode thinking. Maybe the reason why you think
diagrams should play a bigger role is because you are trying to
increase your use of the R-mode.
Maybe the reason why it may be hard for some to agree with you that a
picture is much better than code is because when they are asked to
draw their house, their L-mode rushes in and screams: "House! I know
that one! It's a box with a triangle on top (the roof) and two
rectangles inside it (window and door). Maybe the diagrams you have in
mind to describe software are different from what other people
imagine.
Philip.
On Jun 25, 3:38 pm, Ralf Westphal <i...@ralfw.de> wrote:
> On 25 Jun., 00:56, Jason Catena <jason.cat...@gmail.com> wrote:
>
> > The only way you can say that source code text is one-dimensional and
> > incapable of grand abstraction is if you equate all source code to
> > assembly language.
>
> I mean "one dimensional" in a very basic, physical way: assembler,
> Java, C#, Clojure, Ruby source code is just text.
> And text is just a string of characters which means it´s just a one
> dimensional shape (a line).
>
> Wrapping lines and indenting text does not make much of a difference.
> You still need to scan text from left to right and top to bottom to
> understand it. (At least where a latin alphabet is used as in
> programming languages.)
>
> And then write up a text describing it.
>
> What do you think I´d prefer as a recipient?
> (At least as long as you´re not a literary author like Hemingway or
> the like ;-)
>
> > We´re past that with compilers. All the higher
> > languages raise the level of the conversation, and put great machines
> > at our disposal (DSLs continually raise the bar and simplify the text
> > we need write; the entire apparatus of the internet hidden behind
>
> I´m all for DSLs. Textual as well as graphical.
> Except: I don´t believe many developers will be able to come up with
> their own DSL.
> Some problem domains benefit from a specific DSL. But mostly what we
> need is general purpose DSLs like SQL or RegEx.
>
Raoul Duke
<philip.joh...@googlemail.com> wrote:
> There are two cognitive modes: L-mode and R-mode. L-mode (L for
> linear) gives you these abilities:
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 :)
Andy Dent
On 22/06/2011, at 3:11 PM, Ralf Westphal wrote:
> 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.
Jason Catena
> 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.
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
David Wilde
needs to work on the changed flowerbeds?
b. to new gardeners who have no/little knowledge of the overall
garden?
David
Vlad Dumitrescu
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
Ralf Westphal
> Hallo Ralph,
>
> It's a really interesting discussion here.
>
> Did you ever think of how a great novel could be expressed in pictures and sketches?
the work of Will Eisner.
Or take a look an example like this:
http://www.amazon.com/Logicomix-Search-Truth-Apostolos-Doxiadis/dp/1596914521
Or this one: http://www.amazon.de/Faust-Tragödie-erster-Teil-Flix/dp/3551789770
(a German classic retold)
Or read the work of Scott McCloud starting with:
http://www.amazon.com/Understanding-Comics-Invisible-Scott-Mccloud/dp/006097625X
(it´s about how to tell stories)
Or check out this: http://www.amazon.com/Back-Napkin-Expanded-Problems-Pictures/dp/1591843065
It´s all about how to do "graphical storytelling".
But if you´re more inclined to "facts", have a look at this:
http://www.amazon.com/Cartoon-Guide-Statistics-Larry-Gonick/dp/0062731025
So, would you still say, "pure text" has any advantage over "graphical
languages" per se?
>
> Sometimes text may just be the right level to express something.
Shakespearian sonnett.
But my guess is, that pure text is just best where the main point are,
well, words and their sound.
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.
But as a technical author (read: programmer) I´m interested in
precision, in lossless replication of my images in the heads of my
recipients.
Ralf Westphal
> I think I finally get what Ralf is after. It sounds like he's made some
> progress answering the questions he's posing here, but it's all been in
> German. He'd like to run the same conversation in English to broaden the
> audience. I guess I have to decide whether to invest time in the exercises
> he proposes or stop reading this thread if he's just selling snake oil.
> Tough to tell without seeing more details.
http://geekswithblogs.net/theArchitectsNapkin/category/11899.aspx
Although some are a bit dated (more than a year old), the paradigm I´m
working on is still the same:
http://geekswithblogs.net/theArchitectsNapkin/category/11899.aspx
As the tooling around Flow-Design matures I´ll surely post more on it
in English.
Andreas Leidig
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
Ralf Westphal
> 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*?
The visual designs I have in mind do not overlap with code. They do
not try to do the same you´re doing best with source code. Flow-Design
is not supposed to be a full fledged graphical programming language
like Scratch (http://scratch.mit.edu/).
FD is just focussing on the more coarse grained design. What "coarse
grained" means to you as a designer/programmer, though, is up to
you ;-)
I´m using FD only to design until I reach a granularity where I´m
pretty confident to only need some 50 LOC max to code a functional
unit. (For educational purposes, though, I might use it to model
smaller units of code.)
FD scales very well. A whole application is a functional unit like the
code running in a single process of the application like maybe
filtering records or formatting data is. FD is a visual language for
"stratified designs" (see "Structure and Interpretation of Computer
Programs", p. 140). But it does not contain control structures like
if, while etc. It´s just data flowing and being transformed. Because
software is about just that: transformation of input into output.
The purpose of FD is to make it easy to design the flow of
functionality, to describe the (overall) behavior of software. This is
what sequence diagrams or activity diagrams are trying to do, too. But
FD is trying to do more. It also defines the basic framework of a
software in terms of programming language means. In the end you take a
FD model and translate it into code, either by hand or using a
compiler (see ebclang.codeplex.com). This already works today pretty
well, but the tooling still needs to improve.
So what end up in code is, well, the whole model. All levels of
abstraction. That´s why it can be regenerated from code. You could
even change the code without the model and get a new visual
representation generated from it.
This works with IL code too (decompilation). But the result is poor,
because the original model was poor. Classes and their dependencies don
´t tell much about software actually works, how its parts play
together to transform input into output. In addition a bunch of
classes does not show you the levels of abstraction in processing
data. Strata are not part of the original model and thus don´t show up
in decompiled code.
But the code generated is only part of the picture. FD explicitly does
not strive to generat all code! It´s just the flow of actions. The
actions themselves, the operations, the basic vocabulary of a software
needs to be implemented by hand. Use TDD for that, if you like.
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.
But for higher levels of abstraction use a visual language. And a
visual language, that is, which can be translated into a framework for
code. And a visual language which shows how things actually work. That
´s why FD is a data flow language.
With this fundamental separaction of concerns you can keep your coding
skills but you enhance your design skills. Production is a flow.
Always. Silicium and oil is turned into a computer in many, many
sequential (and parallel steps). Customer data entered by a user is
turned into sales figures. It´s all transformations. So the best way
to express transformations is to use a language focused on that. BPMN
is one example - but it´s too heavyweight for most programming
scenarios. That´s where FD comes in. With its own language (graphical
as well as textual (to get an idea of that have a look at yuml.me)).
>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:
me and it´s quite likely I´m trying to answer your questions :-) So if
you´re missing something, let me know. Any question will also help me
to hone the message/paradigm.
> 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.
hard: the recipient needs to interpret the medium/message.
But the more removed the form of a message is from its final/original
form, the harder such interpretation is, I´d say.
Show me this: http://geekswithblogs.net/theArchitectsNapkin/category/11899.aspx
Or show me a textual description of it.
Which representation will evoke more of the same original image you
had in mind?
>
> * 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
Ralf Westphal
> 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.
And surely the company does not want to be dependent on these guys. So
what if they leave? There will be no one to even ask for a whiteboard
drawing.
> 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).
Even XP guys will agree that an architecture vision will be very, very
stable over the course of a project.
So I´d say: Where volatility is highest, don´t rely on pretty
pictures. Instead stare at the code. But not just any code :-) Keep
code in chunks of maybe 200+ LOC. That´s an amount of code which can
easily be reviewed.
In addition: make these chunks of code as independent of each other as
possible. And I mean: independent. No static dependencies, not even
dynamic dependencies :-)
On the next level of abstraction view these chunks as black boxes. If
you like, group them in any way you wish, e.g. for the purpose of
distributed development or deployment or simple understanding.
In addition: do not concern yourself with code anymore on this higher
level of abstraction. Use a different language for the strata of your
program, a visual language that´s easy to communicate - and whose
elements are translated into code, so the visual models don´t go out
of date.
>
> 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.)
But I guess, we need not give up model-code-synchronicity that
lightly. It can be achieved. Or at least I achieve it in my software -
although this can be made easier with better tools.
>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.
wrong paradigm for coarse grained structuring. OOAD has made it at
least not simpler, if not more difficult to design software.
> > 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.
are on instead of where they most probably lost it ;-)
To raise the level of abstraction for distributed communication or
persistence is important. But it should not be confused with solving
the most pressing issue of software development: correct and evolvable
software systems.
Ralf Westphal
> 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.
Codify those pictures in text also is important.
Translating this text into source code is important.
Being able to "extract" the text from the source code/executable code
is important.
Visualizing the text is important.
We need all five steps.
Ron Jeffries
> 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
Andy Dent
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.
Ron Jeffries
> 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
Andy Dent
On 30/06/2011, at 6:47 PM, Ralf Westphal wrote:
> FD scales very well. A whole application is a functional unit like the
> code running in a single process of the application like maybe
> filtering records or formatting data is. FD is a visual language for
> "stratified designs" (see "Structure and Interpretation of Computer
> Programs", p. 140). But it does not contain control structures like
> if, while etc. It´s just data flowing and being transformed. Because
> software is about just that: transformation of input into output.
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
Raoul Duke
Ralf Westphal
> How do you determine whether the FD you draw is the FD that
> implements what you understand the problem / solution to be?
For that, however, the operations of the FD model need to be
implemented.
(Operations: leafs of the tree of behaviors, lowest level of the
stratified design)
To do that is up to the programmer. If she wants to do it using TDD
that´s just fine. But for each operation that´s a straightforward
task, because through FD you decompose the overall behavior into
operations that are fairly small, sometimes just 5 line of code,
sometimes 200 LOC (plus test code).
All those operations are independent of each other. So testing is very
easy.
David Wilde
Ralf Westphal
BON I did not really know about.
For a while DCI looked promising to me - but in the end - to me - it
remained too much in the OO world to be efficient in design.
On 30 Jun., 17:20, Andy Dent <d...@oofile.com.au> wrote:
> On 30/06/2011, at 6:47 PM, Ralf Westphal wrote:
>
> > FD scales very well. A whole application is a functional unit like the
> > code running in a single process of the application like maybe
> > filtering records or formatting data is. FD is a visual language for
> > "stratified designs" (see "Structure and Interpretation of Computer
> > Programs", p. 140). But it does not contain control structures like
> > if, while etc. It´s just data flowing and being transformed. Because
> > software is about just that: transformation of input into output.
>
> 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 :-)
>
>
> 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 abouthttp://jbrugge.com/blog/2007/05/10/ode-to-solution-based-modeling/which also points to my postinghttp://www.artima.com/forums/flat.jsp?forum=106&thread=158300and 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 ishttps://sites.google.com/a/gertrudandcope.com/www/thedciarchitecturewhich has a brief overview and many links.
Raoul Duke
> BON I did not really know about.
& i thought BON was more for static relationships, than the important
and often hard to grok runtime dynamic relationships?
Andy Dent
On 01/07/2011, at 11:59 PM, Raoul Duke wrote:
>
> & 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!).
Ralf Westphal
FD resource page http://clean-code-advisors.com/ressourcen/flow-design-ressourcen
But how about this: you come up with a challenge and I solve it it the
FD/EBC way.
That way you are sure I dont fake the solution ;-) And I will need to
go off my treaden paths.
Check out the AppKatas to get an idea of the size of such an exercise:
http://geekswithblogs.net/theArchitectsNapkin/archive/2011/06/25/appkata---enter-the-next-level-of-programming-exercises.aspx
It should be from a domain I can get into without asking too many
questions, it should not be trivial (like "store user data and query
it"), it should not require heavy infrastructure.
I would publish the solution with explanations in my English blog.
How's that?
On 1 Jul., 17:06, David Wilde <djwi...@gmail.com> wrote:
> Ralf,
>
> Do you have any examples of FD alongside code? I would like to see it in
> action to get a clearer picture of it.
>
> David
>