Humanist Discussion Group, Vol. 17, No. 386.
Centre for Computing in the Humanities, King's College London
www.kcl.ac.uk/humanities/cch/humanist/
www.princeton.edu/humanist/
Submit to: humanist@princeton.edu
Date: Fri, 07 Nov 2003 08:51:11 +0000
From: Willard McCarty <willard.mccarty@kcl.ac.uk>
Subject: communicating ideas
Following is an exchange begun with a query from me to John Bradley (King's
College London) and Stephen Ramsay (University of Georgia) on how people
who design and write software communicate ideas to each other. It seems
best to us for this to become an open discussion on Humanist. Contributions
most welcome!
Yours,
WM
(1)
>Date: Tue, 04 Nov 2003 10:26:02 +0000
>To: John Bradley <John.Bradley@kcl.ac.uk>, Stephen Ramsay <sramsay@uga.edu>
>From: Willard McCarty <willard.mccarty@kcl.ac.uk>
>>
>John and Stephen,
>
>I am trying at the moment to think through the problem of how we
>communicate what we do in software. I assume that among programmers,
>system designers and the like ideas circulate. How does this in fact
>happen? Sometimes, I suppose, these ideas might take the form of words,
>but I'd think this largely unsatisfactory and so rare. Ideas, I'd guess,
>are better formulated and passed around as bits of code -- lines to
>illustrate this or that approach, perhaps, also routines more or less
>treated as black boxes. I learned as an apprentice to a master programmer,
>so long ago that my experience isn't worth much on this point. I'd be very
>grateful for your comments. Has anyone written persuasively on this topic?
>
>Thanks.
>
>Yours,
>W
(2)
>Date: Tue, 4 Nov 2003 08:33:57 -0500
>From: Stephen Ramsay <sramsay@uga.edu>
>To: Willard McCarty <willard.mccarty@kcl.ac.uk>
>Cc: John Bradley <John.Bradley@kcl.ac.uk>
>Subject: Re: communicating ideas
>
>Hi Willard (and John):
>
>I think this crosses over into the area of software design
>methodologies, which is a vast subject. So much of the design
>methodology literature is concerned not with how one goes about
>designing robust, efficient, modular, extensible (etc.) systems (the
>province of software engineering), but with how one goes about
>thinking through the design of a particular system and communicating
>it to others.
>
>Programmers certainly pass around their initial ideas in prose, but
>in my experience, pictures represent the most popular way to
>communicate ideas about a system. Sometimes these are rather
>informal, but there are several standard diagrammatic notations in
>use. UML (Universal Modeling Language) is popular among
>programmers designing object-oriented systems; ER
>(Entity-Relationship) modeling is almost always used by relational
>database designers. I've attached an example of a UML diagram.
>
>My programs always begins as circles and arrows on graph paper, and
>I almost always use this method when I want to explain to someone
>else how my idea would work. At a certain point, this may progress
>to UML diagrams, and from there, to the specification of an API
>(this function takes x type and returns y value).
>
>I send code snippets to other programmers really in only two cases:
>(1) I'm stuck and I want someone else to help me debug the code, and
>(2) I want to show someone else the typical way to make something
>happen using my API.
>
>Geoff, Stefan, and I have all been working on distributed systems
>for humanities computing. It's interesting that thus far, no one
>has seen anyone else's code. Instead, we've seen each other's APIs,
>storyboards, and diagrams. I suspect that the minute we start
>having to look at each other's actual code, we'll have to go back
>and rethink the encapsulation of the system.
>
>I hope this helps. It has been a most stimulating idea to ponder
>with my morning coffee.
>
>Steve
>
>--
>Stephen Ramsay
>Assistant Professor
>Department of English
>University of Georgia
>email: sramsay@uga.edu
>web: http://cantor.english.uga.edu/
>PGP Public Key ID: 0xA38D7B11
(3)
>From: John Bradley <john.bradley@kcl.ac.uk>
>Date: Tue, 4 Nov 2003 16:10:30 +0000
>To: Willard McCarty <willard.mccarty@kcl.ac.uk>
>Subject: Re: communicating ideas
>Cc: Stephen Ramsay <sramsay@uga.edu>
>
>Willard (and Stephen):
>
>As Stephen says, design methodologies is a vast subject. UML is used to help
>define the structure of a complex system, and is tied to the "Object
>Orientation" way of looking at software development, which is, in fact, a
>substantial change from previous "procedural" techniques. With Object
>Orientation came the idea (mainly in Smalltalk) that complex objects could be
>created which had a bunch of methods -- each of which had only a small amount
>of code in them. Even though the internal code seemed very straightward for
>each method, the overall "capabilities" of the object were sophisticated.
>Beginning smalltalk programmers often reported that it was hard to find, by
>looking at each code chunk itself, where the "real" behaviour of the object
>lived. The implication of this was that a meaningful description of the code
>began to depend less on the code details and more on the overall shape of the
>objects in which the code sits. UML is an attempt (not a fully successful
>one
>in my opinion) to try to (more) formally encapsulate the
>objects/classes/methods/data in a mainly diagrammatical way (although not
>purely diagrammatical -- full UML modelling involves, for example, the
>creation of a "data dictionary" as well as the various diagrams. Stephen has
>shown you one of the several different kinds of diagrams that are defined by
>UML -- but there are others, including ones that emphasize the graphing of
>processing between the classes over time.
>
>To me it seems that the best approach (although I haven't actually done this
>since the early 90's ;-) ) is to convey programming ideas is to intermingle
>prose (in a rather highly structured document) to programmatical elements.
>Knuth was the first person that I know of to think of "literate programming"
>and developed an approach that blended together TeX code (in Pascal!!) with
>text described how it worked. There have been various attempts to formalise
>literate programming and extend it so that it works well with other
>programming
>languages. A bit of this idea lives in JavaDoc, I think.
>
>I don't know how my original programming ideas get passed to others on the
>team
>here. Generally, I prototype some portion of the code -- describe it
>(probably
>badly) out loud with the chunk of code to the person who is today to be
>blessed
>with my idea, and then leave with the cheery words "go and do likewise".
>Sometimes it works. Often I find that diagrams on bits of paper are helpful.
>There are usual several visits to help the poor programmer get a clearer view
>of what is needed. :-<
>
>More formal methods seem to be essential with large distributed programming
>tasks, although I don't know to what extent UML has taken over the
>industry in
>reality. The important part of the process seems to be (in OOP at least) to
>describe the task in terms of an object, its methods and its data. The
>code to
>implement the methods often does not need to be given, and if the OOP
>modelling
>is successful might be in each instance relatively straightforward. Getting
>the object definitions right so that each object is easy to understand, that
>its methods seem obvious and relatively simple, and that they fit together
>properly to perform the needed task is critical, and challenging for the
>designer.
>
>Hope this is some help....
>
>Cheers. ... jb
Dr Willard McCarty | Senior Lecturer | Centre for Computing in the
Humanities | King's College London | Strand | London WC2R 2LS || +44 (0)20
7848-2784 fax: -2980 || willard.mccarty@kcl.ac.uk
www.kcl.ac.uk/humanities/cch/wlm/
This archive was generated by hypermail 2b30 : Fri Nov 07 2003 - 04:12:38 EST