You are on page 1of 12

A Software Design

Specification Template
by Brad Appleton <brad@bradapp.net>
http://www.bradapp.net
Adapted for LAFS by Elliott McCrory
Copyri!ht " #$$%&#$$' by Bradford (. Appleton
Permission is hereby granted to make and distribute verbatim copies of this document provided the copyright
notice and this permission notice are preserved on all copies.
Table of Contents
1. INTRODUCTION...................................................................................................................................1
#.#. ()C*ME+, )*,L-+E...........................................................................................................................
#... ()C*ME+, (ESC/-0,-)+...................................................................................................................%
1.2.1. Introduction.............................................................................................................................4
1.2.2. System Overview.....................................................................................................................
2. DESIGN CONSIDERATIONS..............................................................................................................5
..#. ASS*M0,-)+S A+( (E0E+(E+C-ES....................................................................................................1
.... 2E+E/AL C)+S,/A-+,S.....................................................................................................................1
..3. 2)ALS A+( 2*-(EL-+ES....................................................................................................................4
..%. (E5EL)0ME+, ME,6)(S..................................................................................................................4
3. ARCHITECTURAL STRATEGIES.....................................................................................................6
4. SSTE! ARCHITECTURE................................................................................................................."
%.#. S*BS7S,EM A/C6-,EC,*/E...............................................................................................................8
5. #OLICIES AND TACTICS....................................................................................................................$
6. DETAILED SSTE! DESIGN.............................................................................................................%
4.#. CLASS-F-CA,-)+..................................................................................................................................$
4... (EF-+-,-)+.........................................................................................................................................$
4.3. /ES0)+S-B-L-,-ES.............................................................................................................................#9
4.%. C)+S,/A-+,S...................................................................................................................................#9
4.1. C)M0)S-,-)+...................................................................................................................................#9
4.4. *SES/-+,E/AC,-)+S.........................................................................................................................#9
4.'. /ES)*/CES.......................................................................................................................................#9
4.8. 0/)CESS-+2......................................................................................................................................#9
4.$. -+,E/FACE/E:0)/,S.........................................................................................................................##
4.#9. (E,A-LE( S*BS7S,EM (ES-2+........................................................................................................##
". GLOSSAR...........................................................................................................................................11
$. &I&LIOGRA#H..................................................................................................................................11
1. Introduction
,he followin! i; an atte<pt to p=t to!ether a co<plete yet rea;onably fle>ible
te<plate for the ;pecification of ;oftware de;i!n;. ?here@er po;;ible - ha@e tried to pro@ide
!=ideline; Ain;tead of pre;cribin! reB=ire<ent;C for the content; of @ario=; ;ection; and
;=b;ection; of the doc=<ent. So<e <ay prefer to reB=ire <ore detailed ;=b;ection; of a
partic=lar ;ection choo;in! one or <ore of the ;=b;ection topic; fro< the li;t of !=ideline;
pro@ided. -n thi; ;en;e thi; doc=<ent i; really a te<plate for a te<plate.
-n de@i;in! thi; te<plate - ha@e !leaned infor<ation fro< <any ;o=rce; incl=din!
@ario=; te>t; on Software En!ineerin! A0re;;<an So<<er@ille and 5an 5lietC )bDect&
)riented (e@elop<ent ABooch /=<ba=!h Berard and ?irf;&BrocEC @ario=; SE- report;
/@ar/www/app;/con@er;ion/t<p/;cratchF#/.%488$314.doc 0a!e . of #.
(o(&Std and Mil&Std doc=<entation reB=ire<ent; A.#4'/.#4'AC and -EEE doc=<entation
;tandard; Apartic=larly -EEE&#9#4 for ;oftware de;i!n; and -EEE&839 for ;oftware
reB=ire<ent;C. - ha@e <ade e@ery effort not to a;;=<e or i<po;e a partic=lar ;oftware
de@elop<ent <ethodolo!y or paradi!< and to place <ore e<pha;i; on content than on
for<at.
-t i; <y de;ire that a co<pleted ;oftware de;i!n ;pecification <eet the followin!
criteria:
-t ;ho=ld be able to adeB=ately ;er@e a; trainin! <aterial for new proDect <e<ber;
i<partin! to the< eno=!h infor<ation and =nder;tandin! abo=t the proDect
i<ple<entation ;o that they are able to =nder;tand what i; bein! ;aid in de;i!n
<eetin!; and wonGt feel a; if they are drownin! when they are fir;t a;Eed to create or
<odify ;o=rce code.
-t ;ho=ld ;er@e a; HobDecti@e e@idenceH that the de;i!ner; and/or i<ple<enter; are
followin! thro=!h on their co<<it<ent to i<ple<ent the f=nctionality de;cribed in the
reB=ire<ent; ;pecification.
-t need; to be a; detailed a; po;;ible while at the ;a<e ti<e not i<po;in! too <=ch of a
b=rden on the de;i!ner; and/or i<ple<enter; that it beco<e; o@erly diffic=lt to create
or <aintain.
0lea;e note that there are no ;ection; in thi; doc=<ent for de;cribin! ad<ini;trati@e or
b=;ine;; d=tie; or for propo;in! plan; or ;ched=le; for te;tin! or de@elop<ent. ,he ;ection;
in thi; doc=<ent are concerned ;olely with the de;i!n of the ;oftware. ?hile there are place;
in thi; doc=<ent where it i; appropriate to di;c=;; the effect; of ;=ch plan; on the ;oftware
de;i!n it i; thi; a=thorG; opinion that <o;t of the detail; concernin! ;=ch plan; belon! in one
or <ore ;eparate doc=<ent;.
1.1. Document Outline
6ere i; the o=tline of the propo;ed te<plate for ;oftware de;i!n ;pecification;. 0lea;e
note that <any part; of the doc=<ent <ay be e>tracted a=to<atically fro< other ;o=rce;
and/or <ay be contained in other ;<aller doc=<ent;. ?hat follow; i; D=;t one ;=!!e;ted
o=tline for<at to =;e when atte<ptin! to pre;ent the architect=re and de;i!n of the entire
;y;te< a; one ;in!le doc=<ent. ,hi; by no <ean; i<plie; that it literally i; a ;in!le doc=<ent
Athat wo=ld not be <y per;onal preferenceC:
-ntrod=ction
Sy;te< )@er@iew
(e;i!n Con;ideration;
o A;;=<ption; and (ependencie;
o 2eneral Con;traint;
/@ar/www/app;/con@er;ion/t<p/;cratchF#/.%488$314.doc 0a!e 3 of #.
o 2oal; and 2=ideline;
o (e@elop<ent Method;
Architect=ral Strate!ie;
o ;trate!y&# na<e or de;cription
o ;trate!y&. na<e or de;cription
o ...
Sy;te< Architect=re
o co<ponent&# na<e or de;cription
o co<ponent&. na<e or de;cription
o ...
0olicie; and ,actic;
o policy/tactic&# na<e or de;cription
o policy/tactic&. na<e or de;cription
o ...
(etailed Sy;te< (e;i!n
o <od=le&# na<e or de;cription
o <od=le&. na<e or de;cription
o ...
2lo;;ary
Biblio!raphy
,he abo@e o=tline i; by no <ean; e>cl=;i@e. A partic=lar n=<berin! ;che<e i; not
nece;;arily reB=ired and yo= are <ore than welco<e to add yo=r own ;ection; or ;=b;ection;
where yo= feel they are appropriate. -n partic=lar yo= <ay wi;h to <o@e the biblio!raphy and
!lo;;ary to the be!innin! of the doc=<ent in;tead of placin! the< at the end.
,he ;a<e te<plate i; intended to be =;ed for both hi!h&le@el de;i!n and low&le@el
de;i!n. ,he de;i!n doc=<ent =;ed for hi!h&le@el de;i!n i; a Hli@in! doc=<entH in that it
!rad=ally e@ol@e; to incl=de low&le@el de;i!n detail; Aaltho=!h perhap; the H(etailed (e;i!nH
;ection <ay not yet be appropriate at the hi!h&le@el de;i!n pha;eC.
,he orderin! of the ;ection; in thi; doc=<ent atte<pt; to corre;pond to the order in
which i;;=e; are addre;;ed and in which deci;ion; are <ade d=rin! the act=al de;i!n proce;;.
)f co=r;e it i; =nder;tood that ;oftware de;i!n; freB=ently Aand often fort=natelyC donGt
alway; proceed in thi; order Aor in any linear or e@en predictable orderC. 6owe@er it i; =;ef=l
for the p=rpo;e of co<prehendin! the de;i!n of the ;y;te< to pre;ent the< a; if they did.
FreB=ently one of the be;t way; to doc=<ent a proDectG; de;i!n i; to Eeep a detailed proDect
Do=rnal lo! or diary of i;;=e; a; they are <=lled o@er and bandied abo=t and to record the
deci;ion; <ade Aand the rea;on; whyC in the Do=rnal. *nfort=nately the Do=rnal for<at i; not
=;=ally or!aniIed the way <o;t people wo=ld liEe it for a for<al re@iew. -n ;=ch ca;e; for the
p=rpo;e of re@iew the Do=rnal can be conden;ed and/or portion; of it e>tracted and
reor!aniIed accordin! to thi; o=tline. 6owe@er if thi; i; done then yo= need to choo;e
whether to =pdate and <aintain the de;i!n doc=<ent in the Do=rnal for<at or the for<al
re@iew for<at. -t i; not ad@i;able to try and <aintain the de;i!n doc=<ent in both for<at;. A-f
/@ar/www/app;/con@er;ion/t<p/;cratchF#/.%488$314.doc 0a!e % of #.
yo= ha@e an a=to<ated <ethod of con@ertin! the Do=rnal into a for<al doc=<ent then thi;
proble< i; ;ol@ed.C
1.2. Document Description
6ere i; the de;cription of the content; Aby ;ection and ;=b;ectionC of the propo;ed
te<plate for ;oftware de;i!n ;pecification;:
1.2.1. Introduction
0ro@ide an o@er@iew of the entire doc=<ent:
(e;cribe the p=rpo;e of thi; doc=<ent
(e;cribe the ;cope of thi; doc=<ent
(e;cribe thi; doc=<entG; intended a=dience
-dentify the ;y;te</prod=ct =;in! any applicable na<e; and/or @er;ion n=<ber;.
0ro@ide reference; for any other pertinent doc=<ent; ;=ch a;:
o /elated and/or co<panion doc=<ent;
o 0rereB=i;ite doc=<ent;
o (oc=<ent; which pro@ide bacE!ro=nd and/or conte>t for thi; doc=<ent
o (oc=<ent; that re;=lt fro< thi; doc=<ent Ae.!. a te;t plan or a de@elop<ent
planC
(efine any i<portant ter<; acrony<; or abbre@iation;
S=<<ariIe Aor !i@e an ab;tract forC the content; of thi; doc=<ent.
+ote:
For the re<ainin! ;ection; of thi; doc=<ent it i; concei@able Aand perhap; e@en
de;irableC that one or <ore of the ;ection topic; are di;c=;;ed in a ;eparate de;i!n doc=<ent
within the proDect. For each ;ection where ;=ch a doc=<ent e>i;t; a reference to the
appropriate de;i!n doc=<ent i; all that i; nece;;ary. All ;=ch e>ternal Aor fra!<entedC de;i!n
doc=<ent; ;ho=ld probably be pro@ided with thi; doc=<ent at any de;i!n re@iew;.
1.2.2. System Overview
0ro@ide a !eneral de;cription of the ;oftware ;y;te< incl=din! it; f=nctionality and
<atter; related to the o@erall ;y;te< and it; de;i!n Aperhap; incl=din! a di;c=;;ion of the
ba;ic de;i!n approach or or!aniIationC. Feel free to ;plit thi; di;c=;;ion =p into ;=b;ection;
Aand ;=b;=b;ection; etc ...C.
/@ar/www/app;/con@er;ion/t<p/;cratchF#/.%488$314.doc 0a!e 1 of #.
2. Design Considerations
,hi; ;ection de;cribe; <any of the i;;=e; which need to be addre;;ed or re;ol@ed
before atte<ptin! to de@i;e a co<plete de;i!n ;ol=tion.
2.1. Assumptions and Dependencies
(e;cribe any a;;=<ption; or dependencie; re!ardin! the ;oftware and it; =;e. ,he;e
<ay concern ;=ch i;;=e; a;:
/elated ;oftware or hardware
)peratin! ;y;te<;
End&=;er characteri;tic;
0o;;ible and/or probable chan!e; in f=nctionality
2.2. General Constraints
(e;cribe any !lobal li<itation; or con;traint; that ha@e a ;i!nificant i<pact on the
de;i!n of the ;y;te<G; ;oftware Aand de;cribe the a;;ociated i<pactC. S=ch con;traint; <ay be
i<po;ed by any of the followin! Athe li;t i; not e>ha=;ti@eC:
6ardware or ;oftware en@iron<ent
End&=;er en@iron<ent
A@ailability or @olatility of re;o=rce;
Standard; co<pliance
-nteroperability reB=ire<ent;
-nterface/protocol reB=ire<ent;
(ata repo;itory and di;trib=tion reB=ire<ent;
Sec=rity reB=ire<ent; Aor other ;=ch re!=lation;C
Me<ory and other capacity li<itation;
0erfor<ance reB=ire<ent;
+etworE co<<=nication;
5erification and @alidation reB=ire<ent; Ate;tin!C
)ther <ean; of addre;;in! B=ality !oal;
)ther reB=ire<ent; de;cribed in the reB=ire<ent; ;pecification
2.3. Goals and Guidelines
(e;cribe any !oal; !=ideline; principle; or prioritie; which do<inate or e<body the
de;i!n of the ;y;te<G; ;oftware. S=ch !oal; <i!ht be:
/@ar/www/app;/con@er;ion/t<p/;cratchF#/.%488$314.doc 0a!e 4 of #.
,he J-SS principle AHJeep it ;i<ple ;t=pidKHC
E<pha;i; on ;peed @er;=; <e<ory =;e
worEin! looEin! or Hfeelin!H liEe an e>i;tin! prod=ct
For each ;=ch !oal or !=ideline =nle;; it i; i<plicitly ob@io=; de;cribe the rea;on for
it; de;irability. Feel free to ;tate and de;cribe each !oal in it; own ;=b;=b;ection if yo= wi;h.
2.4. Development Methods
Briefly de;cribe the <ethod or approach =;ed for thi; ;oftware de;i!n. -f one or <ore
for<al/p=bli;hed <ethod; were adopted or adapted then incl=de a reference to a <ore
detailed de;cription of the;e <ethod;. -f ;e@eral <ethod; were ;erio=;ly con;idered then each
;=ch <ethod ;ho=ld be <entioned alon! with a brief e>planation of why all or part of it wa;
=;ed or not =;ed.
3. Arcitectural Strategies
(e;cribe any de;i!n deci;ion; and/or ;trate!ie; that affect the o@erall or!aniIation of
the ;y;te< and it; hi!her&le@el ;tr=ct=re;. ,he;e ;trate!ie; ;ho=ld pro@ide in;i!ht into the Eey
ab;traction; and <echani;<; =;ed in the ;y;te< architect=re. (e;cribe the rea;onin!
e<ployed for each deci;ion and/or ;trate!y Apo;;ibly referrin! to pre@io=;ly ;tated de;i!n
!oal; and principle;C and how any de;i!n !oal; or prioritie; were balanced or traded&off. S=ch
deci;ion; <i!ht concern Ab=t are not li<ited toC thin!; liEe the followin!:
*;e of a partic=lar type of prod=ct Apro!ra<<in! lan!=a!e databa;e library etc. ...C
/e=;e of e>i;tin! ;oftware co<ponent; to i<ple<ent @ario=; part;/feat=re; of the
;y;te<
F=t=re plan; for e>tendin! or enhancin! the ;oftware
*;er interface paradi!<; Aor ;y;te< inp=t and o=tp=t <odel;C
6ardware and/or ;oftware interface paradi!<;
Error detection and reco@ery
Me<ory <ana!e<ent policie;
E>ternal databa;e; and/or data ;tora!e <ana!e<ent and per;i;tence
(i;trib=ted data or control o@er a networE
2eneraliIed approache; to control
Conc=rrency and ;ynchroniIation
Co<<=nication <echani;<;
Mana!e<ent of other re;o=rce;
Each ;i!nificant ;trate!y e<ployed ;ho=ld probably be di;c=;;ed in it; own
;=b;ection or Aif it i; co<ple> eno=!hC in a ;eparate de;i!n doc=<ent Awith an appropriate
/@ar/www/app;/con@er;ion/t<p/;cratchF#/.%488$314.doc 0a!e ' of #.
reference here of co=r;eC. MaEe ;=re that when de;cribin! a de;i!n deci;ion that yo= al;o
di;c=;; any other ;i!nificant alternati@e; that were con;idered and yo=r rea;on; for reDectin!
the< Aa; well a; yo=r rea;on; for acceptin! the alternati@e yo= finally cho;eC. So<eti<e; it
<ay be <o;t effecti@e to e<ploy the Hpattern for<atH for de;cribin! a ;trate!y.
!. System Arcitecture
,hi; ;ection ;ho=ld pro@ide a hi!h&le@el o@er@iew of how the f=nctionality and
re;pon;ibilitie; of the ;y;te< were partitioned and then a;;i!ned to ;=b;y;te<; or
co<ponent;. (onGt !o into too <=ch detail abo=t the indi@id=al co<ponent; the<;el@e; Athere
i; a ;=b;eB=ent ;ection for detailed co<ponent de;cription;C. ,he <ain p=rpo;e here i; to !ain
a !eneral =nder;tandin! of how and why the ;y;te< wa; deco<po;ed and how the indi@id=al
part; worE to!ether to pro@ide the de;ired f=nctionality.
At the top&<o;t le@el de;cribe the <aDor re;pon;ibilitie; that the ;oftware <=;t
=ndertaEe and the @ario=; role; that the ;y;te< Aor portion; of the ;y;te<C <=;t play. (e;cribe
how the ;y;te< wa; broEen down into it; co<ponent;/;=b;y;te<; Aidentifyin! each top&le@el
co<ponent/;=b;y;te< and the role;/re;pon;ibilitie; a;;i!ned to itC. (e;cribe how the hi!her&
le@el co<ponent; collaborate with each other in order to achie@e the reB=ired re;=lt;. (onGt
for!et to pro@ide ;o<e ;ort of rationale for choo;in! thi; partic=lar deco<po;ition of the
;y;te< Aperhap; di;c=;;in! other propo;ed deco<po;ition; and why they were reDectedC. Feel
free to <aEe =;e of de;i!n pattern; either in de;cribin! part; of the architect=re Ain pattern
for<atC or for referrin! to ele<ent; of the architect=re that e<ploy the<.
-f there are any dia!ra<; <odel; flowchart; doc=<ented ;cenario; or =;e&ca;e; of
the ;y;te< beha@ior and/or ;tr=ct=re they <ay be incl=ded here A=nle;; yo= feel they are
co<ple> eno=!h to <erit bein! placed in the (etailed Sy;te< (e;i!n ;ectionC. (ia!ra<; that
de;cribe a partic=lar co<ponent or ;=b;y;te< ;ho=ld be incl=ded within the partic=lar
;=b;ection that de;cribe; that co<ponent or ;=b;y;te<.
+ote:
,hi; ;ection Aand it; ;=b;ection;C really applie; only to newly de@eloped Aor yet&to&
be de@elopedC portion; of the ;y;te<. -f there are part; of the ;y;te< that already e>i;ted
before thi; de@elop<ent effort be!an then yo= only need to de;cribe the pre&e>i;tin! part;
that the new part; of the ;y;te< depend =pon and only in eno=!h detail ;=fficient to de;cribe
the relation;hip; and interaction; between the old part; and the new part;. 0re&e>i;tin! part;
that are <odified or enhanced need to be de;cribed only to the e>tent that i; nece;;ary for the
reader to !ain a ;=fficient =nder;tandin! of the nat=re of the chan!e; that were <ade.
4.1. Subsystem Architecture
-f a partic=lar co<ponent i; one which <erit; a <ore detailed di;c=;;ion than what
wa; pre;ented in the Sy;te< Architect=re ;ection pro@ide that <ore detailed di;c=;;ion in a
;=b;ection of the Sy;te< Architect=re ;ection Aor it <ay e@en be <ore appropriate to de;cribe
/@ar/www/app;/con@er;ion/t<p/;cratchF#/.%488$314.doc 0a!e 8 of #.
the co<ponent in it; own de;i!n doc=<entC. -f nece;;ary de;cribe how the co<ponent wa;
f=rther di@ided into ;=bco<ponent; and the relation;hip; and interaction; between the
;=bco<ponent; A;i<ilar to what wa; done for top&le@el co<ponent; in the Sy;te<
Architect=re ;ectionC.
-f any ;=bco<ponent; are al;o dee<ed to <erit f=rther di;c=;;ion then de;cribe the<
in a ;eparate ;=b;ection of thi; ;ection Aand in a ;i<ilar fa;hionC. 0roceed to !o into a; <any
le@el;/;=b;ection; of di;c=;;ion a; needed in order for the reader to !ain a hi!h&le@el
=nder;tandin! of the entire ;y;te< or ;=b;y;te< Ab=t re<e<ber to lea@e the !ory detail; for
the (etailed Sy;te< (e;i!n ;ectionC.
-f thi; co<ponent i; @ery lar!e and/or co<ple> yo= <ay want to con;ider
doc=<entin! it; de;i!n in a ;eparate doc=<ent and ;i<ply incl=din! a reference to it in thi;
;ection. -f thi; i; the option yo= choo;e the de;i!n doc=<ent for thi; co<ponent ;ho=ld ha@e
an or!aniIational for<at that i; @ery ;i<ilar Aif not identical toC thi; doc=<ent.
". #olicies and Tactics
(e;cribe any de;i!n policie; and/or tactic; that do not ha@e ;weepin! architect=ral
i<plication; A<eanin! they wo=ld not ;i!nificantly affect the o@erall or!aniIation of the
;y;te< and it; hi!h&le@el ;tr=ct=re;C b=t which nonethele;; affect the detail; of the interface
and/or i<ple<entation of @ario=; a;pect; of the ;y;te<. S=ch deci;ion; <i!ht concern Ab=t
are not li<ited toC thin!; liEe the followin!:
Choice of which ;pecific prod=ct to =;e Aco<piler interpreter databa;e library etc. ...C
En!ineerin! trade&off;
Codin! !=ideline; and con@ention;
,he protocol of one or <ore ;=b;y;te<; <od=le; or ;=bro=tine;
,he choice of a partic=lar al!orith< or pro!ra<<in! idio< Aor de;i!n patternC to
i<ple<ent portion; of the ;y;te<G; f=nctionality
0lan; for en;=rin! reB=ire<ent; traceability
0lan; for te;tin! the ;oftware
0lan; for <aintainin! the ;oftware
-nterface; for end&=;er; ;oftware hardware and co<<=nication;
6ierarchical or!aniIation of the ;o=rce code into it; phy;ical co<ponent; Afile; and
directorie;C.
6ow to b=ild and/or !enerate the ;y;te<G; deli@erable; Ahow to co<pile linE load
etc. ...C
Each partic=lar policy or ;et of tactic; e<ployed ;ho=ld probably be di;c=;;ed in it;
own ;=b;ection or Aif it i; lar!e or co<ple> eno=!hC in a ;eparate de;i!n doc=<ent Awith an
appropriate reference here of co=r;eC. MaEe ;=re that when de;cribin! a de;i!n deci;ion that
yo= al;o di;c=;; any other ;i!nificant alternati@e; that were con;idered and yo=r rea;on; for
reDectin! the< Aa; well a; yo=r rea;on; for acceptin! the alternati@e yo= finally cho;eC. For
/@ar/www/app;/con@er;ion/t<p/;cratchF#/.%488$314.doc 0a!e $ of #.
thi; rea;on it <ay freB=ently be con@enient to =;e one of the <ore pop=lar Hpattern for<at;H
to de;cribe a !i@en tactic.
For thi; partic=lar ;ection it <ay beco<e diffic=lt to decide whether a partic=lar
policy or ;et of tactic; ;ho=ld be di;c=;;ed in thi; ;ection or in the Sy;te< Architect=re
;ection or in the (etailed Sy;te< (e;i!n ;ection for the appropriate co<ponent. 7o= will
ha@e to =;e yo=r own Hbe;tH D=d!e<ent to decide thi;. ,here will =;=ally be ;o<e !lobal
policie; and tactic; that ;ho=ld be di;c=;;ed here b=t deci;ion; abo=t interface; al!orith<;
and/or data ;tr=ct=re; <i!ht be <ore appropriately di;c=;;ed in the ;a<e A;=bC;ection a; it;
corre;pondin! ;oftware co<ponent in one of the;e other ;ection;.
$. Detailed System Design
Mo;t co<ponent; de;cribed in the Sy;te< Architect=re ;ection will reB=ire a <ore
detailed di;c=;;ion. )ther lower&le@el co<ponent; and ;=bco<ponent; <ay need to be
de;cribed a; well. Each ;=b;ection of thi; ;ection will refer to or contain a detailed de;cription
of a ;y;te< ;oftware co<ponent. ,he di;c=;;ion pro@ided ;ho=ld co@er the followin!
;oftware co<ponent attrib=te;:
.1. Classi!ication
,he Eind of co<ponent ;=ch a; a ;=b;y;te< <od=le cla;; pacEa!e f=nction file
etc. ....
.2. De!inition
,he ;pecific p=rpo;e and ;e<antic <eanin! of the co<ponent. ,hi; <ay need to
refer bacE to the reB=ire<ent; ;pecification.
.3. "esponsibilities
,he pri<ary re;pon;ibilitie; and/or beha@ior of thi; co<ponent. ?hat doe; thi;
co<ponent acco<pli;hL ?hat role; doe; it playL ?hat Eind; of ;er@ice; doe; it pro@ide to it;
client;L For ;o<e co<ponent; thi; <ay need to refer bacE to the reB=ire<ent; ;pecification.
.4. Constraints
Any rele@ant a;;=<ption; li<itation; or con;traint; for thi; co<ponent. ,hi;
;ho=ld incl=de con;traint; on ti<in! ;tora!e or co<ponent ;tate and <i!ht incl=de r=le; for
interactin! with thi; co<ponent Aenco<pa;;in! precondition; po;tcondition; in@ariant;
other con;traint; on inp=t or o=tp=t @al=e; and local or !lobal @al=e; data for<at; and data
acce;; ;ynchroniIation e>ception; etc.C
/@ar/www/app;/con@er;ion/t<p/;cratchF#/.%488$314.doc 0a!e #9 of #.
.#. Composition
A de;cription of the =;e and <eanin! of the ;=bco<ponent; that are a part of thi;
co<ponent.
.. $ses%&nteractions
A de;cription of thi; co<ponent; collaboration; with other co<ponent;. ?hat other
co<ponent; i; thi; entity =;ed byL ?hat other co<ponent; doe; thi; entity =;e Athi; wo=ld
incl=de any ;ide&effect; thi; entity <i!ht ha@e on other part; of the ;y;te<CL ,hi; concern;
the <ethod of interaction a; well a; the interaction it;elf. )bDect&oriented de;i!n; ;ho=ld
incl=de a de;cription of any Enown or anticipated ;=bcla;;e; ;=percla;;e; and <etacla;;e;.
.'. "esources
A de;cription of any and all re;o=rce; that are <ana!ed affected or needed by thi;
entity. /e;o=rce; are entitie; e>ternal to the de;i!n ;=ch a; <e<ory proce;;or; printer;
databa;e; or a ;oftware library. ,hi; ;ho=ld incl=de a di;c=;;ion of any po;;ible race
condition; and/or deadlocE ;it=ation; and how they <i!ht be re;ol@ed.
.(. )rocessin*
A de;cription of preci;ely how thi; co<ponent; !oe; abo=t perfor<in! the d=tie;
nece;;ary to f=lfill it; re;pon;ibilitie;. ,hi; ;ho=ld enco<pa;; a de;cription of any al!orith<;
=;edM chan!e; of ;tateM rele@ant ti<e or ;pace co<ple>ityM conc=rrencyM <ethod; of creation
initialiIation and clean=pM and handlin! of e>ceptional condition;.
.+. &nter!ace%,-ports
,he ;et of ;er@ice; Are;o=rce; data type; con;tant; ;=bro=tine; and e>ception;C
that are pro@ided by thi; co<ponent. ,he preci;e definition or declaration of each ;=ch
ele<ent ;ho=ld be pre;ent alon! with co<<ent; or annotation; de;cribin! the <eanin!; of
@al=e; para<eter; etc. .... For each ;er@ice ele<ent de;cribed incl=de Aor pro@ide a
referenceC in it; di;c=;;ion a de;cription of it; i<portant ;oftware co<ponent attrib=te;
ACla;;ification (efinition /e;pon;ibilitie; Con;traint; Co<po;ition *;e; /e;o=rce;
0roce;;in! and -nterfaceC.
M=ch of the infor<ation that appear; in thi; ;ection i; not nece;;arily e>pected to be
Eept ;eparate fro< the ;o=rce code. -n fact <=ch of the infor<ation can be !leaned fro< the
;o=rce it;elf Ae;pecially if it i; adeB=ately co<<entedC. ,hi; ;ection ;ho=ld not copy or
reprod=ce infor<ation that can be ea;ily obtained fro< readin! the ;o=rce code Athi; wo=ld be
an =nwanted and =nnece;;ary d=plication of effort and wo=ld be @ery diffic=lt to Eeep =p&to&
dateC. -t i; reco<<ended that <o;t of thi; infor<ation be contained in the ;o=rce Awith
appropriate co<<ent; for each co<ponent ;=b;y;te< <od=le and ;=bro=tineC. 6ence it i;
e>pected that thi; ;ection will lar!ely con;i;t of reference; to or e>cerpt; of annotated
/@ar/www/app;/con@er;ion/t<p/;cratchF#/.%488$314.doc 0a!e ## of #.
dia!ra<; and ;o=rce code. Any referenced dia!ra<; or ;o=rce code e>cerpt; ;ho=ld be
pro@ided at any de;i!n re@iew;.
.1.. Detailed Subsystem Desi*n
0ro@ide a detailed de;cription of thi; ;oftware co<ponent Aor a reference to ;=ch a
de;criptionC. Co<ple> dia!ra<; ;howin! the detail; of co<ponent ;tr=ct=re beha@ior or
infor<ation/control flow <ay be incl=ded in the ;=b;ection de@oted to that partic=lar
co<ponent Aaltho=!h =nle;; they are @ery lar!e or co<ple> ;o<e of the;e dia!ra<; <i!ht be
<ore appropriately incl=ded in the Sy;te< Architect=re ;ection. ,he de;cription ;ho=ld co@er
any applicable ;oftware co<ponent attrib=te; A;o<e of which <ay be adeB=ately de;cribed
;olely by a ;o=rce code declaration or e>cerptC.
%. &lossary
An ordered li;t of defined ter<; and concept; =;ed thro=!ho=t the doc=<ent.
'. (i)liograpy
A li;t of referenced and/or related p=blication;.
Brad Appleton <brad@bradapp.net>
http://www.bradapp.net
/@ar/www/app;/con@er;ion/t<p/;cratchF#/.%488$314.doc 0a!e #. of #.

You might also like