 |
Agile Modeling (AM) is a practices-based software
process whose scope is to describe how to model and
document in an effective and agile manner. On the
AM
home page I state that one of the goals of AM is to
address the issue of how to apply modeling techniques on
software projects taking an agile approach such as
eXtreme Programming (XP),
Dynamic Systems
Development Method (DSDM), and
Scrum to name a few. Because the
scope of XP is much greater than that of AM, XP covers
the full development lifecycle, it is a candidate
"base process" into which the techniques of AM
may be tailored. Furthermore, although XP clearly
includes modeling as part of its process it is not as
explicit about how to do so as many developers would
prefer. Hence an opportunity for AM. Luckily
XP, like AM, is also an agile practices-based
methodology which makes the conceptual fit between the
two methods much easier than between AM and a process such as the
Rational
Unified Process (RUP) the topic of the article Agile
Modeling and the Unified Process.
|
|
Table of Contents
- Setting the
record straight
- XP and AM?
- AM throughout the XP
lifecycle
- How do you make this work?
There are several common
misconceptions that people seem to have regarding
modeling on an XP project.
The three most common misconceptions are that you
don’t model on an XP project, that you don’t
document on an XP project, or that if you do model your
only options are the modeling artifacts of the UML. I’ll address these misconceptions in turn in this section,
but first I want to explore why they occur so that you
can recognize other misconceptions when they arise.
From what I can gather based on the conversations
on the
AM mailing list
the source of these misconceptions is often the result
of one or more of the following:
-
Second-hand knowledge of XP.
The Internet is a major source of information
for many developers, in particular newsgroups and
emails from colleagues.
As people learn a new technique they often
join a newsgroup or mailing list, such as the
extremeprogramming list,
and start monitoring the group/list.
Someone will post something, which may not be
accurate, and many people will accept it as
official, particularly when they haven’t had an
opportunity yet to try it out for themselves.
Don’t believe everything that you hear.
-
Questionable sources of
information regarding XP.
It’s often hard to determine the quality of
published material, be it electronic or printed
form. Sometimes honest mistakes are made, that’s happened to me
more than once, and sometimes people publish
misleading information on purpose.
When you’re just learning a new subject you
often cannot distinguish between high-quality
sources of information and questionable ones.
If you base your understanding on
questionable sources it is very easy to get the
wrong idea about XP.
-
Difficulty seeing beyond
their current environment.
Many developers find themselves in
less-than-ideal environments.
XP requires you to adopt practices that are
often foreign to your current environment, pair
programming and test-first development are new to most
organizations, and sometimes these practices simply
aren’t feasible to adopt.
If you cannot adopt the practice of pair
programming then XP isn’t going to work for you,
but instead of proclaiming that XP doesn’t work in
their environment many people will instead proclaim
that XP doesn’t work at all.
The reality is that XP does in fact work in
the right situations, it is just that your situation
may not be one of the right ones.
-
Too much focus on the word
“extreme”.
XP’s name is both one of its greatest
strengths its greatest weaknesses.
Because of the name when some people hear
XP’s advice to travel light, to reduce the amount
of documentation that you create and maintain, that
they instead translate it to “create no
documentation at all”.
That’s extreme, right?
Or they’ll hear XP’s advice to use simple
modeling techniques such as
user stories and
CRC
cards and somehow translate that advice to “you
don’t model at all.”
That’s extreme, right?
Sigh.
In this section I will set the
record straight regarding the three most common issues
concerning modeling and XP:
User stories are a fundamental aspect of XP and
artifacts such as Class Responsibility Collaborator
(CRC) cards are common to XP efforts.
User stories provide a high-level overview of the
requirements for a system -- they are reminders to have
a conversation with your project stakeholders regarding
their requirements -- and are used to as a primary input into estimating
and scheduling, and drive the development of acceptance
test cases. CRC
cards are used to explore structure, perhaps for
conceptual modeling to understand the problem domain or
for design to work through the structure of your
software. User
stories and CRC cards are both models, see the
Artifacts for AM article, so therefore modeling is clearly a
part of XP. XP
developers will also create sketches, often on a
whiteboard or a piece of paper, whenever user stories
and CRC cards aren’t the best option.
In
Extreme Programming Explained, the first book written about XP, Kent Beck
includes hand-drawn sketches of class diagrams and other
free-form diagrams.
In fact, in the second edition he includes a mind map in
the inside cover overviewing XP.
The bottom line is that modeling is a fundamental
aspect of XP, something that I explore in detail in this
article.
Documentation is also an important
part of XP.
Ron Jeffries offers the following advice:
“Outside your extreme
programming project, you will probably need
documentation: by all means, write it.
Inside your project, there is so much verbal
communication that you may need very little else.
Trust yourselves to know the difference.”
There are several interesting
implications of that statement.
First and foremost, the XP community recognizes
that documentation should be produced for people
external to your team, people that AM would term project
stakeholders. Second,
it points out that verbal communication between team
members reduces the need for documentation within the
team. This
is the result of project team members being co-located,
making communication easier, as well as aspects of XP
such as Pair Programming and
Collective
Ownership that promote communication between
developers. As
I discuss in the article on Communication
documentation is only one form of communication, one
that is typically the least effective, that can be
easily replaced by more effective techniques such as
face-to-face communication.
Third, it recognizes that sometimes you do in
fact need internal documentation for your team. This is consistent with the advice presented in
Extreme
Programming Installed where the authors point out that
information resulting from conversations with your
project stakeholders regarding user stories are captured
as additional documentation attached to the card.
More on this in the Section A
Closer Look At the XP Lifecycle.
Fourth, it suggests that XP team members should
know when documentation is required and be allowed to
act accordingly. Fifth,
it implies that you should trust the team and give them
control over their own destiny.
This can be hard in many organizations.
If the team is untrustworthy then you have a
serious problem that needs to be dealt with, this is
true regardless of whether they are following XP, or if
they are trustworthy but your organizational culture
doesn’t allow you to act based on that trust then once
again you have a serious problem to deal with.
Another problem is that when you are an outsider
to an XP team, when you haven’t been actively involved
in the conversations and interactions that have replaced
the need for documentation, that it appears that there
isn’t enough documentation.
When this is the case, instead of forcing the
team to write documentation instead invest the time to
determine if they need the documentation that you
believe is missing – suggest the documentation to the
team, and if there is an actual need for it then
they’ll create it.
As Ron Jeffries likes to say, “It’s called
Extreme Programming not stupid programming”. Finally,
the most important implication for XP teams is that if
you need documentation then write it.
The need for documentation on an XP
project is reduced by several of its practices.
First, because of
test-first development and a focus
on
acceptance testing there is always a working test
suite that shows that your system works and fulfills the
requirements implemented to that point.
For the developers, these tests act as
significant documentation because it shows how the code
actually works. When
you think about it, this makes a lot of sense.
When you are learning something new do you prefer
to read a bunch of documentation or do you look for
source code samples?
Many developers prefer to start at source code
samples, and the test suite provides these samples.
Second, XP’s focus on simplicity and practice
of
refactoring result in very clean and clear code.
If the code is already easy to understand, why
invest a lot of time writing documentation to help you
to understand it? This
applies to both internal and external documentation –
why add comments to code that is already clear and
unambiguous? If
the code isn’t so, then refactor it to improve its
quality or as a last resort write documentation.
Even though some development environments make it
easy to include documentation in your code, Java’s
Javadoc utility is such an example, you only want to
invest in documentation when it makes sense to do so and
not just because it is easy.
What confuses many people regarding
XP and documentation is that XP doesn’t specify
potential documents to create during development.
This is unlike the
RUP which suggests a slew of potential project
artifacts. Instead,
the suggestion is to work together with your project
stakeholders in an environment of rapid feedback and
trust them to determine the things that they need,
not
just documents but any type of project enhancements. Once
again, you need to have the courage to trust the people
involved with the project.
In the article Agile
Documentation I discuss a collection of documents
that you may choose to create and provide advice for
when to consider creating them.
One of the greatest
misunderstandings people have about XP regards concept
of traveling light – many people believe that it means
you don’t create any documentation, but nothing could
be further from the truth.
What traveling light actually means is that you
create just enough models and documentation, too little
or too much puts you at risk.
As I suggest in Agile
Documentation a good rule of thumb to ensure that
you’re traveling light is that you shouldn’t create
a model or document until you actually need it –
creating either thing too early puts you at risk of
wasting your time working on something you don’t
actually need yet.
An important thing to understand
about documentation on an XP project is that it is a
business decision, not a technical one.
This is consistent with AM’s philosophy
regarding documentation, discussed in Agile
Documentation. Jeffries
says it best:
“If there is a need for a
document, the customer should request the document in
the same way that she would request a feature: with a
story card. The
team will estimate the cost of the document, and the
customer may schedule it in any iteration she
wishes.”
See the article XP and
the UML? Clearly the Wrong Question to be
Asking
2. AM and XP?
AM should be tailored into an
existing, full lifecycle methodology, in order to
improve its approach to modeling.
Because modeling is clearly a part of XP, see
above, the potential exists for AM to add value to an XP
project. This
assumes of course that there is possible to tailor AM
into XP, I believe it is and argue so below, and that
you can do so without detracting from what currently
exists within XP. In
particular, XP’s practices of refactoring and
test-first development clearly do a very good job of filling
in for two critical goals – promoting clean design and
thinking through your design before writing code –
that are typically associated with traditional modeling
processes. My
experience is that both refactoring and test-first
development are complementary to AM and arguably enablers of
several AM practices, as I argue below.
In this section I explore the following issues:
A critical issue that must be
addressed is how well AM fits with XP.
Table 1 lists the practices
of AM and either maps them to existing principles or
practices of XP or discusses the potential fit of the AM
practice when it is not explicitly a part of XP.
Because XP was used as a foundation for AM many
of the practices map straight to XP.
However, because AM’s focus is on modeling
several practices are clearly new, hence the potential
for AM to bring value to an XP project.
Table 1. Applicability of AM
Practices on an XP Project.
|
AM Practice
|
Fit With XP
|
|
Active Stakeholder
Participation
|
This practice is simply a new
take on XP’s On-Site Customer practice.
AM uses the term project stakeholder in
place of customer and focuses on the concept of
their active participation, hence Active
Stakeholder Participation and not On-Site
Stakeholder.
|
|
Apply
Modeling Standards
|
This is the AM version of
XP’s
Coding Standards practice.
|
|
Apply
Patterns Gently
|
This practice reflects the
YAGNI principle to the effective application of
patterns within your system, in conformance to
XP’s practice of Simple Design.
|
|
Apply
the Right Artifact(s)
|
This practice is not
explicitly described by XP principles and
practices although is very much aligned with XP
philosophies of “if you need it do it” and
using the most appropriate tool or technique for
the job at hand.
|
|
Collective
Ownership
|
AM has adopted XP’s Collective
Ownership practice.
|
|
Create
Several Models in Parallel
|
This is a modeling-specific
practice. XP
developers can clearly work on several models –
such as CRC cards, acceptance test cases, and
sketches – if they choose to do so.
|
|
Create
Simple Content
|
This is complementary XP’s Simple
Design practice that advises to keep your
models as simple as possible.
|
|
Depict
Models Simply
|
This is complementary XP’s Simple
Design practice that suggests that your models
do not need to be fancy to be effective, perfect
examples of which are CRC cards and user stories.
|
|
Discard
Temporary Models
|
This practice reflects XP’s
Travel Light principle, which AM has
adopted, explicitly advising you to dispose of
models that you no longer need.
|
|
Display
Models Publicly
|
This practice reflects XP’s
(and AM’s) value of Communication,
principle of Open & Honest Communication
(adopted by AM), and reflects its practice of Collective
Ownership.
|
|
Formalize
Contract Models
|
This practice is not
currently reflected within XP, well perhaps in its
“if you need to then do it” philosophy.
This practice was included in AM to provide
guidance for how to deal with the very common
situation of integrating with other systems.
|
|
Iterate
to Another Artifact
|
This practice explicitly
states, in a general form, the practice of XP
developers to iterate between working on various
artifacts such as source code, CRC cards, and
tests.
|
|
Model
in Small Increments
|
This practice supports XP’s
iterative and increment approach to development.
Both XP and AM prefer an emergent approach
to development and not a
big design up front (BDUF)
approach.
|
|
Model
With Others
|
This is the AM version of
XP’s Pair Programming practice.
|
|
Prove
it With Code
|
This is the AM version of
XP’s Concrete Experiments principle.
In fact, it was originally called Concrete
Experiments although was renamed when it was
evolved into a practice.
|
|
Reuse
Existing Resources
|
This concept is not
explicitly included in XP, although it clearly
isn’t excluded either.
XP developers are practical, if there is
something available that can be appropriately
reused then they will likely choose to do so.
|
|
Single Source Information |
The goal of storing information in a single place
reflects the XP concept of traveling light. |
|
Update
Only When it Hurts
|
This practice reflects AM and
XP’s Travel Light principle, advising
that you should only update an artifact only when
you desperately need to.
|
|
Use
the Simplest Tools
|
This practice reflects AM and
XP’s Assume Simplicity principle and is
consistent with XP’s preference for low-tech
tools such as index cards for modeling.
|
The fact that AM’s practices are
complementary to XP isn’t sufficient; there should
also be a philosophical alignment between the two
methodologies as well.
I believe that there is.
First, AM has adopted the four values
of XP – Courage, Simplicity, Communication,
and Feedback – and added a fifth one, Humility,
one that is clearly compatible with XP.
Second, the
principles
of AM are closely aligned with those of XP.
Nine of eighteen are adopted directly from XP,
and the remaining ones –
Software is Your Primary
Goal,
Enabling the Next Effort is Your Secondary
Goal,
Model With a Purpose,
Multiple
Models,
Content is More Important Than
Representation,
Everyone Can Learn From Everyone
Else,
and
maximize stakeholder ROI – are
clearly compatible with XP’s philosophies.
The three modeling-specific principles may cause
a hard-core XP developer to pause for a moment, but on
reflection should not prove arguable. Model With a Purpose advises that you shouldn’t work
on a model without good cause,
Multiple
Models
says that you have a wide range of techniques available
to you that you may choose to apply (including but not
limited to CRC cards, user stories, and the diagrams of
the UML).
Refactoring is a
technique to restructure code in a disciplined way, a
technique that is a fundamental practice of XP.
The basic idea is that you make small changes to
your code, called refactorings, to support new
requirements and/or to keep your design as simple as
possible. The advantage of refactoring is that it
enables programmers to safely and easily evolve their
code to fulfill new requirements or to improve its
quality.
Is refactoring compatible with AM? Yes. Refactoring
is a coding technique whereas AM does not address
programming-related issues, therefore there is no
technical overlap between the two.
What about a conceptual overlap?
AM address design modeling and refactoring
addresses design improvement of source code.
This begs the question “What do you do when you
have an existing design model and you refactor your
code?” Although
it’s an interesting question, the real issue is that
you have two artifacts, a design model and source code,
that describe the design of your system.
One has changed, the source code, now you need to
decide whether or not you wish to update the model.
The way that you originally arrived at the model
is irrelevant to this issue, you could have gotten there
because you took an AM approach to develop it, you could
have taken a BDUF approach, or you could adopted an
existing model and are coding to it (for example,
several organizations have developed persistence
frameworks based on the design that I present at http://www.ambysoft.com/persistenceLayer.html).
The issue is irrelevant of the type of design
model, be it a UML class diagram, CRC cards, a physical
data model, or a procedural structure chart.
The good news is that AM provides advice for how
to deal with such a situation, in particular the
practice Discard
Temporary Models suggests that you should
consider whether you really need the design model and
then if not get rid of it and the practice Update
Only When it Hurts suggests that it’s often
reasonable to have artifacts such as the design model
and the code out of sync.
So how do you apply AM and
refactoring together?
Simple. Apply
AM practices as appropriate when you are modeling, use
those models as input into your programming efforts, and
refactor your code as you normally would have.
If you discover that you need to attempt a major
refactoring, get the team together to discuss it,
modeling whenever appropriate, then approach the major
refactoring as you would have in the past: as a
collection of small refactorings.
Modeling tools that reverse-engineer your code can
prove valuable when you are refactoring code,
particularly when you are unfamiliar with that code.
Many developers think visually, they grasp information
communicated via pictures more readily than they do
information communicated textually, so CASE tools that
quickly import a bit of code and create diagrams from
them can be very useful. It's quite common for
CASE tools to import object-oriented source code,
perhaps written in Java or C++, and generate UML class
diagrams that show the static structure of the code and
UML sequence diagrams that depict its dynamic nature.
These diagrams can be used to quickly understand the
existing code, the first step in refactoring it.
Test-first development is a
development practice where you work in very short cycles
where you consider a test, write the test and business
code for it, get it to work, then continue. These tests are collected into a development integration
testing suite that must be successfully run whenever
code is submitted into your shared repository.
This practice is integral to XP.
Is test-first development
compatible with AM?
Yes. Like
refactoring, test-first development is more of a coding
practice so there is little opportunity for technical
overlap. However, there is room for conceptual overlap because
test-first development clearly delves into the realm of
detailed design since it provides developers with an
opportunity to think through their code before they
write it (as well as important feedback regarding their
code). If you’ve chosen to do a little modeling before writing
your code, perhaps to think through an issue larger than
a single test case, then that’s okay.
In fact, it may even make your test-first
development efforts easier, because you've thought
things through better.
How do you apply AM within a
test-first development environment?
As with refactoring, simply apply AM practices as
appropriate when you are modeling, use those models as
input into your programming efforts, and iterate between
modeling,
testing, and programming as needed. For
more details, read the
AMDD article.
Only the ones that add value to what your team is
trying to accomplish. Ideally that will at least
be the core practices of AM, therefore it would be fair
to claim that you are in fact “doing AM”, and
perhaps even adopt the supplementary practices as well.
It is important to note that your goal isn’t simply to
be able to say that you’re agile modeling, it is to
improve your productivity as software developers.
To explain how the practices of AM can be applied on
an XP I will work through a portion of the
SWA
Online Case Study and show how modeling
is used throughout the XP lifecycle in the article AM
and XP: AM Throughout the XP Lifecycle.
How should you approach modeling
during development on an XP project?
Beck suggests that you should apply the XP
practice of Small Initial Investment and draw a
few pictures at a time.
He states that the XP strategy is that anyone can
design with pictures all they want, but as soon as a
question is raised that can be answered with code then
the designers must turn to code for the answer.
In other works you should then seek Rapid
Feedback to discover whether your pictures are on
target by following the AM practice Prove
it With Code.
When should you consider modeling
during development on an XP project?
Whenever creating a model is more effective that
writing code. In
other words, follow the AM principle
maximize stakeholder ROI and the AM practice Apply
the Right Artifact(s).
How should you model?
Follow AM’s practice Use
the Simplest Tools and prefer tools such as
index cards, whiteboards, and Post It notes over more
complicated CASE tools.
Simple tools tend to promote interaction and
communication, two factors that are critical to your
success. Although
XP favors the use of index cards to record user stories,
CRC models, and story tasks there is nothing wrong with
using a CASE tool as long as its use provides positive
value to your effort.
How should you document?
XP teams prefer to write clean,
easy-to-understand source code – their philosophy is
that only the source code is in sync with the source
code. However,
remember that AM’s principle Model
With A Purpose states that you should understand
the needs of a model/document’s audience.
If the audience for documentation is your
system’s users or your senior management then clean
source code isn’t going to do it, instead you will
need to develop external documentation for this
audience. Your
stakeholders should request this documentation and
should understand the costs involved, one of which is
the fact that any time you spend writing documentation
isn’t spent writing software, and be willing to accept
those costs.
XP developers need to recognize that you can model on
an XP project, that modeling is in fact a part of XP
already with its existing application of user stories
and CRC cards. More importantly, XP developers
must abandon any preconceived notions that they may have
about modeling - that
big modeling up front (BMUF) is
the only approach to modeling, that models are permanent
documents that must always be updated, that you need to
use complex CASE tools to model, and that the UML
defines the only models available to you - and approach
modeling from a new perspective. One such
perspective was presented in this article, that you can
tailor Agile Modeling (AM) into a software process based
on eXtreme Programming (XP) and still remain effective
as software developers.
 |
|
The Object Primer 3rd Edition: Agile Model Driven
Development with UML 2 is an
important reference book for agile modelers,
describing how to develop 35
types of agile
models including all 13
UML 2 diagrams.
Furthermore, this book describes the techniques
of the
Full Lifecycle Object Oriented Testing
(FLOOT) methodology to give you the fundamental
testing skills which you require to succeed at
agile software development. The book also
shows how to move from your agile models to
source code (Java examples are provided) as well
as how to succeed at implementation techniques
such as
refactoring and
test-driven development
(TDD). The Object Primer also includes a
chapter overviewing the critical database
development techniques (database refactoring,
object/relational mapping,
legacy analysis, and
database access coding) from my award-winning
Agile Database Techniques
book. |
 |
|
Agile Modeling: Effective Practices for Extreme
Programming and the Unified Process is the seminal
book describing how agile software developers approach
modeling and
documentation. It describes principles and
practices which you can tailor into your existing
software process, such as
XP, the
Rational Unified Process (RUP), or the
Agile Unified Process (AUP), to streamline your
modeling and documentation efforts. Modeling and
documentation are important aspects of any software
project, including agile projects, and this book
describes in detail how to
elicit requirements,
architect, and then
design your system in an agile manner. |
 |
|
The Elements of UML 2.0 Style describes a collection
of standards, conventions, and
guidelines
for creating effective
UML diagrams. They are based on sound, proven
software engineering principles that lead to diagrams
that are easier to understand and work with. These
conventions exist as a collection of simple, concise
guidelines that if applied consistently, represent an
important first step in increasing your productivity as
a modeler. This book is oriented towards
intermediate to advanced UML modelers, although there
are numerous examples throughout the book it would not
be a good way to learn the UML (instead, consider
The Object Primer). The book is a brief 188
pages long and is conveniently pocket-sized so it's easy
to carry around. |
Their Figure 4.1
Their Figure 6.2
This figure applies a
UML-based data modeling notation that I first introduced
in The Object Primer 2/e (Ambler, 2001a) and
later evolved for Mastering EJB 2/e (Roman,
Ambler, Jewell, & Marinescu, 2002).
We actively work with clients around the world to
improve their information technology (IT) practices,
typically in the role of mentor/coach, team lead, or trainer. A full
description of what we do, and how to contact us, can be
found at Scott W.
Ambler + Associates.
 
|
