Design Practice Reference: Guides and Templates to Craft Quality Software in Style

126 Pages·2021·17.495 MB·English

by  Olaf Zimmermann, Mirko Stocker

Design Practice Reference
Guides and Templates to Craft Quality Software in Style
Olaf Zimmermann and Mirko Stocker
Thisbookisforsaleathttp://leanpub.com/dpr
Thisversionwaspublishedon2022-11-02
ThisisaLeanpubbook.LeanpubempowersauthorsandpublisherswiththeLeanPublishing
process.LeanPublishingistheactofpublishinganin-progressebookusinglightweighttoolsand
manyiterationstogetreaderfeedback,pivotuntilyouhavetherightbookandbuildtractiononce
youdo.
©2021-2022OlafZimmermannandMirkoStocker
Wewouldliketodedicatethisbooktotheworld-widecommunityofarchitects,developers,method
creators,andbloggersthatcreatedandpopularizedthemethodelementsthisbookisallabout.
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Whoshouldreadthisbook?Andwhy? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Methods:TheGood,TheBad,andTheWhy . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
GeneralMethodAdoptionPrinciple:BePragmatic! . . . . . . . . . . . . . . . . . . . . . . . . 4
TheTemplates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
BookContent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
TheGitHubRepositoryCompaniontothisBook. . . . . . . . . . . . . . . . . . . . . . . . . . 5
CurrentStatusofBookandRepository. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
AbouttheAuthors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
IntroductiontoDPR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
ContentOrganizationandTerminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
OverviewandDependencies(Steps) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
QuickLinks(GettingStarted) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
OtherMethod/PracticeCollections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
ActivitiesReference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
ArchitecturalDecisionCapturing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
ArchitectureModeling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
SMARTNFRElicitation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
StorySplitting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
StrategicDomain-DrivenDesign(DDD) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Tactic(al)Domain-DrivenDesign(DDD) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
UserInterfaceMocking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
StepwiseServiceDesign. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
ArtifactsReference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
ArchitecturalDecisionRecord(Y-Statement) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Components,Responsibilities,Collaborations(CRC)Card . . . . . . . . . . . . . . . . . . . . 65
DomainModel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
DDDContextMap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
UseCase(Model) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
UserStories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
APIDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
CONTENTS
CandidateEndpointList(CEL) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
RefinedEndpointList(REL) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
ServiceLevelAgreement(SLA) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
RolesReference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
ApplicationandIntegrationArchitect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
APIProductOwner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
ExamplesofDPRinAction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Story1:ArchitecturalDecisionCapturingMatters . . . . . . . . . . . . . . . . . . . . . . . . 107
Story2:UserStoriesvs.UseCasesvs.Both . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Story3:PatternsforAPIDesignanditsLakesideMutualCaseStudy . . . . . . . . . . . . . 108
MoreExamples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
CriticalReviewandDiscussion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Whenandwhennottogo“deeper” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Wheretostartexploring? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Reallymightyandenabling? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
DonewithDPR:What’sNext? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
CheatSheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
BacklogofMissingMethodElements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Copyright,Trademarks,Disclaimers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Preface
Our Design Practice Repository (DPR) on GitHub¹, first released in the fall of 2020, collects proven
method elements and other knowledge nuggets for API and service design — and agile software
architecture work in general. In this book companion to the repository, we keep the acronym DPR
(pronounced“deeper”),meaning“DesignPracticeReference”here.
Whilewedoapplyandteachthemethodelementspresentedinthisbook,veryfewofthem
areourowncreations;the“OriginsandSignofUse”sectionsthroughoutthebookwilltell
you which ones are. All their descriptions in this book, including background information
and examples, certainly are ours (unless marked as citations). So expect many links to
originalsourcesandsupplementalmaterial—butalsofreshcontent,includingtipsandtricks
formethodadoption,rootedinpersonalandtribalprojectexperience.
Who should read this book? And why?
Herearetheroleswecreatedthebookandtherepositoryfor,orderedfromgenerictospecific:
• Anysoftwareengineer
• Anysoftwarearchitect
• SoftwarearchitectsspecializingonapplicationintegrationandAPIs
• APIproductmanagers/owners,developers,testers,maintainers
• (Micro-)Service²designers
WhatcanITprofessionalsinoneormoreoftheserolesdowiththebookcontent?Itsusecasesare:
1. Technical leaders and autonomous teams can use DPR to decide whether to use a particular
practiceinagivenproblemcontext(ornot).
2. Experiencedprofessionalscanrefreshtheirmemoryonhowtoapplyapracticeandwhattoput
inanartifact;newcomerscanfindpointerstotutorialsandtrainings.
3. Reviewerscanusethebookcontentasrefereewhenrevisingorreviewingspecifications,models,
andsoon.
¹https://github.com/socadk/design-practice-repository
²https://medium.com/olzzio/seven-microservices-tenets-e97d6b0990a4
Preface 2
As the use cases suggest, this is a reference book, not a tutorial or textbook. You will find
small examples in it, and many more are available online. We provide many links (that
hopefullywillnotdistractyou),whichwewillupdateonabesteffortbaseinfutureversions
ofDPR.
Asageneralintroductiontosoftwarearchitecture,CesarePautassooffershislecturenoteson“Soft-
wareArchitecture”³onLeanpubaswell(Pautasso2020).Youcanfindmorebookrecommendations
inthearticle“TheSoftwareArchitect’sRoleintheDigitalAge”⁴.
We do teach the method elements featured in Chapters 2 and 3 (Activity Reference, Artifact
Reference) on bachelor, master, and continued education levels, and we apply them regularly on
ourownprojects.Justlikethemethodelements,ourknowledgeand experiencewiththemkeepon
evolving and (hopefully) growing. Hence, a Leanpub ebook seems to be very well suited to share
ourcurrentknowledge,experience,andopinions.
More background information can be found in Chapter 5 “A Critical Review” of this book and in
theblogpost“DesignPracticeRepository(DPR)—ACollectionof‘Mighty’MethodElements”⁵.
Methods: The Good, The Bad, and The Why
Readonifyouagreeonthis:
We all learn well (if not best) from mistakes — but do these mistakes always have to be
ourown?
YoumightbethinkingthatmethodsareontheothersideofcoolintheageofAgile,searchengines,
andonlinedevelopercommunities.Wholikestobebossedaroundbystiffprocessesandforms?Why
not simply look up solutions to problems online? Well, it depends on the problem at hand whether
suchad-hocapproachisadequate,effective,andefficient.
You’llprobablynottakeatopographicmapandafirst-aidkitwithyouwhenyougotothenearest
supermarket,butwhatifyouheadforamulti-dayhikingtripintheAlps?
Letusseewhythetwoofusarepassionateaboutpracticesandtemplates.
³https://leanpub.com/software-architecture
⁴http://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=7725214
⁵https://medium.com/olzzio/design-practice-repository-dpr-ed5e9d0e91cd
Preface 3
Olaf’sTake.Methodscanactuallybecoolorevenlit(likable,instrumental,trustworthy)—
whenengineeredandappliedproperly.They(andtheircreators)shouldhavean“enabling
attitude”⁶ratherthana“directingattitude”⁷one.⁸Iappreciateguidesandadvicethatcome
across as friendly mentors as, for instance, books and online posts by Gregor Hohpe⁹ and
RebeccaWirfs-Brock¹⁰do—(Icollectothersourcesinmyblog¹¹).
WhyamIopentosuchadvice?IwanttobeefficientinanythingIdo.Specificallyinsoftware
analysis, design, and development, I want to get to the domain- and technology-specific
work as soon as possible; the less time I have to spend on establishing and agreeing on
document structures and notations, the better. I do not want to forget anything important
—forinstance,aquestiontoakeystakeholderwhenassessingthearchitecturalsignificance
ofarequirementordesignissue¹².
In summary, I view methods as tour guides rather than lawyers.¹³ And after more than 25
yearsinITandsoftwaredevelopment,Idecidedtocreateonenow—moreprecisely,compile
acollectionofmethodelements(oldandnew)thatIhaveusedandstillusemyselfregularly.
Mirko’sTake.Yes,methodscanbecoolandfun.Sometimes.Maybe.Tobehonest,mostof
thetime,Iwouldratherjuststartwritingcodeandbringthatmentalpictureofthesolution
to life as quickly as possible. In my imagination, the solution is already perfect and will
workoutbeautifully.Inreality,itturnsoutthatitisnotalwaysthateasy.Sowhilefollowing
methodsandproducingartifacts–otherthancode–can,ofcourse,beafunactivity,theyare
oftenalsonecessaryanddistinguishhackingsomethingtogetherinahurryfromdeliberate
softwareengineering.
In the past few months, I’ve used DPR to copy a Use Case artifact-template, find a link to
a wireframing tool whose name I forgot, send a colleague a link to explainDDD concepts
andre-readSMARTNFRstoprepareforaprojectreview.Sowhetherweareusingmethods
forfunornot,Ihopethatourcollectionofpracticesandtemplatesarejustasusefultoour
readersastheyaretome.Ofcourse,notwoprojectsarealike,soletuspickthebitsthatfit
aproject/problembest,andfeelfreetoignoretherest.
SoDPRisaboutsharingknowledgeandexchangingexperience(regardingwhatworkedforus).This
explains the deliberate absence of any bossing around or “directing attitude” in these motivating
positioning statements and throughout the book. In our humble opinions, one can and should not
norm the order of execution of engineering activities. Hence, the DPR templates offer and propose
some structure but do not mandate any notation or execution order (or try to enforce compliance
withone).
⁶https://martinfowler.com/bliki/EnablingAttitude.html
⁷https://martinfowler.com/bliki/DirectingAttitude.html
⁸Doesthe“should”inthissentencealreadyviolatetheprinciple?
⁹https://architectelevator.com/book/cloudstrategy/
¹⁰http://wirfs-brock.com/blog/
¹¹https://ozimmer.ch/index/2020/04/15/BlogHighlightsAndOutlook.html
¹²https://ozimmer.ch/practices/2020/09/24/ASRTestECSADecisions.html
¹³Anotheranalogywouldbesports–coachesandrefereesarebestifnotnoticed,butagreatgametakesplace,andattentionisonthe
players.
Preface 4
General Method Adoption Principle: Be Pragmatic!
To be able to meet our objectives (see above), we established three “rules” for method engineering
andadoptionforus(andthecommunity?):¹⁴
1. Context matters. What works well for one role in a particular client, team, and
project environment might be a major source of headache and trouble elsewhere.
Anygeneraladvice¹⁵shouldmakeitscontext,usagecriteria,andlimitationsexplicit.
2. If in doubt, leave it out. Do not create a method monster (or “big ball of method
mud”); always have a distinct target audience and its information needs in mind
when creating a template or other method element — and when adopting it for a
project.Testyourcreationsyourselfbeforerelease.
3. Value purpose/usefulness over conformity. Do not follow templates and process
advicebythebook,butadoptthemtoyourneeds.Noblindobedienceorcargocults¹⁶!
Whenitcomestoextendingamethod,twomorerulesapply:
4. Donotreinventthewheel,butlookforexistingtemplatesandtweakthemasneeded.
Onlycreatesomethingnewifyoudonotfindwhatyouarelookingfor.¹⁷
5. Acknowledge and reference your input properly. . We actually created some light
toolingtobeabletocitefrom.bibtexsourcesandprovideafull-fledgedbibliography
attheendofthisbook.
Havingfollowedtheserules,muchofwhatDPRoffersisnotnewbutminedfromexistingpractices
andexperience.Ifyouarefamiliarwithsomeofthemethodelements,viewthisbookasareference
manual that provides a curated, integrated view as well as fresh examples, motivating stories, and
adoptionhintscapturingreal-worldexperiencewiththemethodelements.
The Templates
All role, activity, and artifact descriptions are structured according to templates. These templates
mix terminology from OMG SPEM¹⁸ and existing methods; they also take some inspiration from
the Agile Alliance Glossary¹⁹. They range from context and motivation to input and output to
template/checklist/how-tos to examples to origins and signs of use, ending with pointers to other
partsofDPRandtoothermethods.
¹⁴Arewedirectingorenablinghere?Well,theseareruleswehavesetforourselvesasmethodengineers,sowe’dsayitisoktobealittle
moreassertivethanintheactualmethodcontent.
¹⁵https://martinfowler.com/bliki/LimitationsOfGeneralAdvice.html
¹⁶https://en.wikipedia.org/wiki/Cargo_cult
¹⁷yes,lookingforexistingmaterialtakestimeandcanbelessfunthaninventingsomethingonyourown
¹⁸https://www.omg.org/spec/SPEM/2.0/PDF
¹⁹https://www.agilealliance.org/agile101/agile-glossary/
Preface 5
Wedonotfeaturethetemplatestructureshereinthebook;alltemplatesareavailableinthe
GitHubrepository.Itscontributingfolder²⁰containsguidingcommentsonthepurposeand
desiredcontentofeachsection:ActivityTemplate,ArtifactTemplate,andRoleTemplate.²¹
Book Content
This book has seven chapters, “Introduction to DPR”, “Activities Reference”, “Artifacts Reference”,
“RolesReference”,“ExamplesofDPRinAction”,“CriticalReviewandDiscussion”,and“Donewith
DPR: What’s Next?”. There are appendices, providing a “Cheat Sheet” and a “Backlog of Missing
MethodElements”.
The first chapter, “Introduction to DPR”, gives an overview of the content organization. Activities
and techniques supporting these activities are covered in the following second chapter. Artifacts
and templates for them are then covered in the third chapter, followed by a short chapter on roles.
The book concludes with three chapters that feature examples and stories for/from applying DPR
elementsinpractice,discussestheadoptionofDPR,andsummarizesbriefly.Theappendicesprovide
abibliographyaswellasacheatsheet(whentousewhat?)andabacklogofmissingcontent.
Thereisnoneedtoreadfromend-to-end (thisisapracticereference,afterall):
1. Thefirstchapter“IntroductiontoDPR”suggestsstartingpoints.
2. Thefirstpageineachofthefollowingthreechaptersliststheactivities,artifacttemplates,and
roledescriptionsinthem.
3. The closing chapters “Examples of DPR in Action” and “Done with DPR: What’s Next?” also
suggestplacestogo.
The GitHub Repository Companion to this Book
The Design Practice Repository (DPR)²², a public GitHub repository, complements this book. The
repository also collects and references practices and artifacts from various software engineering
andarchitecturedesignmethodsthatareapplicabletoserviceanalysisanddesign²³(andbeyond).
Bookandrepositoryfeaturethesamecontentbutpresentitsomewhatdifferently.
²⁰https://github.com/socadk/design-practice-repository/blob/master/contributing
²¹Tipsfortemplateconstruction(anyformorquestionnaire,actually):1.Filladraftversionoutyourselftogetafeelfortheeffortrequired.
Ifyoustruggle,chancesareyourtargetaudiencewilldosotoo(andofcourse,youcareaboutthat).2.Whenaddingsomethingtoanexisting
template,trytoeliminatesomethingelseandmakesureyoudonotaskforthesameinformationtwice.
²²https://github.com/socadk/design-practice-repository
²³https://ozimmer.ch/patterns/2020/07/06/MicroservicePositions.html