Can Code alone convey design information?

Is code sufficient for someone to understand the design or additional
artifacts needed such as external design documentation?

People learn in many ways. People have a preferred method of
learning. Some of the current methods of learning are identified as
Visual, Auditory, Reading/Writing, and Kinesthetic. In the absence of
a physical handicap to one of the sensory systems, I feel that most
people have a preferred method of learning for specific topics. When
studying literature I find that learning through reading suffices for
me. When studying architecture I find that visual learning is most
appealing. When studying music I find that listening to music is more
meaningful to me than reading the score. When studying mathematical
topics I find that at some times a formula suffices and at other
times I need a plot or graph. As well when studying chemistry,
sometimes formulas suffice but other times 3D visualizations of
compounds increase my ability and speed to learn. Does this mean that
I am not a visual, nor an auditory, nor a reading/writing learner but
that I am a Kinesthetic learner?

I read this description of a Kinesthetic learner:
The Kinesthetics group learns through all of the senses being
stimulated, they also like suitable analogies, real life examples, or
metaphors, and they learn through application.

I am not sure what "type" of learning I am, but I do feel that I do
learn and I do it through many different ways. I use all of my
senses to internalize experience.

To me there is significant difference in these two statements:
"Internalize in the same way" (methods of learning)
"Internalize the same" (results of learning)

Internalize in some way refers to the preferred method of learning. I
might prefer to internalize the design of a software system through
the examination of UML diagrams, or I may internalize the design of
a software system through the reading of the source code. Two
different methods or ways of internalizing a software design. People
that prefer UML are people that prefer to internalize the software
design in the same way.

Internalize the same refers to understanding the correct attributes
of the topic. You can see with your eyes and hear with your ears but
do you understand within your heart. The eyes and ears are the ways
to internalize. The understanding within the heart is that one has
truly understood. True understanding can come though many ways, but
there is only one understanding.

Since I am not formally trained in the field of Learning, my terms
and definitions may not be standard, but if one will be patient in my
weakness then maybe some learning can occur.

Since I know I have learned through Visual, Auditory, Reading/Writing
(VAR) then I know I use methods of information presentation based on
all of these. I also believe that one can learn to consume new
methods of presentation which may become a preferred method of
presentation for specific topics. To me it is not conceivable that
someone is limited to only one of these but my research on the topic
leads me to believe that there are those that do believe that some
are limited to one of these presentation methods in order to learn.
Working on this assumption (which seems counter intuitive) let's
consider the question that has been before the XP group.

Is code sufficient for someone to understand the design or additional
artifacts needed such as external design documentation?

Let's suppose you learn through reading. XP seems to be optimized for
this type of learner. After researching in five texts on XP I found
that four of the books do not mention the topic of UML. I found all
five to focus on little or no documentation. Also simple design and
refactoring are the focus of discussion when referring to design.

Simple and intent revealing is the description of how source code
should be. Why should the code be this way? To avoid ambiguity. If
the code is to communicate the design of the system it needs to do so
with little or no ambiguity. "Code-talkers" is what I call people
that can do this. These people can read and write code easily and
through this they can build an understanding of a design that
encompasses the code.

Code-talkers preferred method of presentation is Reading and Writing.
Given a team of code-talkers the hope is that each will understand
the same design when they read the same code.

I feel that the idea of using code to both capture a design and
convey a design seems reasonable since all programmers clearly write
code. But I wonder this, is the preferred method of presentation to
learn something also the same method the person would use to present
the thing that was learned. If you are good at learning through
reading does that make you a good writer? If you are good at learning
through graphs and charts does that make you capable of producing
quality graphs and charts? If a programmer is good at capturing a
design in code does it mean that he is good at conveying a design
through code?

I imagine that there are many that can learn visually through the
studying and viewing of paintings. Out of those students of the
visual arts, how many of them can communicate through the same
medium, how many of them can paint? There seems to be a difference in
the way one can learn and the way one can teach or share what they
have learned.

But back to the question at hand, is the code sufficient to convey a
design or are additional artifacts necessary. If you can only learn
with a single method of presentation then it would seem that in XP
being a Reader would be advantageous. But what if your XP team is
made up of a few people that prefer to study design through UML
diagrams? In order to get feedback from the entire team there will
have to be two methods of presentation of the design, one in code and
one in UML. Granted both are visual but are significantly different.
I have met many programmers that are code-talkers that can't
understand a UML diagram. By introducing these diagram-talkers with
these code-talkers the effort for communicating design has increased.
Is it worth this increased work?

I suggested the following idea to the XP discussion group:
Maybe it would be better to hire people for your team that has the
same preferred method of presentation of design in order to decrease
the effort in communication.

A concern was pointed out that having people that "think alike" would
be detrimental to creativity.

Do preferred methods of presentation affect one's creativity? The
thought of me being more creative than someone else just because I
can read seems arrogant. The idea that some method of presentation
can stimulate more creative thought seems incorrect as well. Chinese
are renowned for their ancient wisdom and philosophy. I imagine that
the ancient Chinese taught their students with written text (but not
limited to that method alone). Should modern students of philosophy
switch to studying in Chinese in order to stimulate more create
thoughts? What of the ancient Greek philosophers. Were they not
considered to be creative in the field of philosophy? But we have two
different types of written language, one phonetic and one pictorial.
But I delve into areas where I have superficial knowledge, that is,
the history of education in ancient China and ancient Greece.

Is a blind person incapable of being as creative as a seeing person?
A deaf person to a hearing person? I seem to recall that Beethoven
wrote symphonies while he was deaf. Granted Beethoven once heard
sound, but he didn't lose his creativity with the loss of the ability
to hear.

People with high IQ's are not necessarily considered creative
individuals either.

Were the ancient Aborigines of Australia less creative than the
Renaissance man of Italy of France?

It is suggested that creativity is not recognized in its own time but
recognized at a later date. Large steps forward in some field are
often not recognized for their foresight and worth for many years.

A definition of creativity I like because it allows for everyone to
be creative is this - creativity is work hard and going the extra
mile to produce a quality product for a given domain. Practice and
not innate talent seperates the creative from the mere compitent
technician. (These definitions were found on the web).

I conclude that a team made up of people with different preferred
methods of presentation does not increase or descrease the creativity
of the team.

So, if creativity is not at risk then what is wrong with hiring
people with the same preferred method of presenting design?
(Remember we are working under the premise that some people have only
one preferred method of receiving information, Reader/Writer, Visual,
or Auditory. I personally don't think people are so one-dimensional).
Would not not increase accurate communication? If you have to present
the design in code an UML do both descriptions describe the same
thing?

Eventhough I think hiring people that prefer the same methods of
presentation will not hurt creativity, I don't feel that it is
realistic. When hiring a programmer there are many important factors
that must be considered.
From my experience most developers can read code well and understand
UML well. If they are deficient in an area I have seen people learn
how to read a UML diagram. Learning to read code is not as easy.

This brings me to XP's concern of simple and intent revealing code.
These two considerations are necessary inorder to have a chance at
using the code as the design document or in other words "reading
code."

My first concern is that there is no such thing as simple code.
Simple code is so subjective that few can agree on even the most well
known algorithm's varied implementations as to which implementation
is the simplest.

I would suggest that we can determine if code is over-engineered.
Over-engineerd code is code that has functionality that is never
called upon or used. TDD and DBU both address this by only writing
code that is needed. In Object Oriented programming you will see over-
engineered classes that have many overloaded methods to do the same
thing. The overloaded methods exist just incase someone wants to call
the class in a slightly different way. These types of methods don't
come about if one designs code using DBU or TDD.

Intent revealing code is also important. This is done through careful
use of names, naming conventions, and coding conventions. Code
comments can be helpful if kept up to date.

So, if you have intent revealing code that is not over-engineered and
you have code-talkers you can have the code be the design as long as
the only audience of the design is the programmers. If someone that
is outside of the team wants to see a design then you have a
situation. XP addresses this by saying the design isn't really want
you want to see (these aren't the droids you are looking for), you
want to see delivered and working code.

If you use UML to describe the design does that mean you don't care
about not over-engineered code and code that does not reveal its
intent. No.

Do methods embrace diversity or do they seek conformity? Do methods
seek out people that are alike in some way? Once again I will use XP
as an example.

Pair programming is part of XP. This is needed inorder to assist with
design as you go and making sure that the code is not over-engineered
and intent revealing. I know a programmer that has a diagnosed
disorder in which he is terrified of close interaction with people.
This person is not capable of pair programming. Does XP reach out to
this person seeking their unique contributions or does it shun this
person because of his inability to pair program.

I remember a study where it was shown that women learn better in
quiet environments and men learn better where there is background
commotion. With the common work area of XP does this environment
empower the person that needs quiet and no distractions or does it
reject this persons because they can not excel in the environment?

If we are going to require certain abilities from the team then are
there other abilities that should be required?

Any methodology will exclude one set of attributes while inviting
another set.

It has been suggested by a friend that programming itself is a Visual
task and has rewarded only the visual learners and excluded the
others. I can imagine this to be true.

In conclusion I feel that most people have varied preferred methods
of presentation for different topics. I also feel than many people
can learn new methods of presentation. A person that prefers a
particular method of presentation when receiving information doesn't
mean that person is capable of using that same method of presentation
when conveying what they know or understand. People with the same
preferred method of presentation do not think alike, two readers can
read the same text and come to different conclusions. Creativity is
not controlled by a person's preferred method of presentation.
Methodologies optimize for certain characteristics and exploits the
commonality. XP needs people that can work in pairs, work in
environments that potentially have more commotion than say a private
office, and can understand software design through reading code.