Java Coding Standards: BSSC 2005 (2) Issue 1.0

BSSC 2005(2) Issue 1.
Java Coding Standards
Prepared by: ESA Board for Software Standardisation and Contro (BSSC)
european space agency / agence spatiale europenne

!"10# rue $ario"%i&is# '5'(! PA)IS CE*E+# ,ran-e
BSSC 2005(2) Issue 1.0 *.C/$E%0 S0A0/S S1EE0
ii
Document Status Sheet

*.C/$E%0 S0A0/S S1EE0 1. *.C/$E%0 0I02E: BSSC 2005(2) Issue 1.0 2. ISS/E 0 (. )E3ISI.% 1 4. *A0E 1062(6200( 5. )EAS.% ,.) C1A%5E %ew do-u7ent *istin-tion ru es and re-o77endations# se-urity infor7ation added to t8e se-uri" ty -8apter# 9arious -orre-tions# e abora" tion on rea "ti7e :a9a0$ 2 -8apter# - ean"up of a-rony7s and ter7s# intro" du-tory te;t added to ea-8 -8apter# 7er<er casting and template -8apters. %ew se-tions >.5# 1(.4 )ewor&ed and strea7 ined draft. ,irst draft (restru-tured) for open re" 9iew. Issues fro7 re9iew round in-orporated. E;tensi9e restru-turin<. $ateria added on rea "ti7e :a9a# se-urity# and portabi " ity. Co77ents of P8i ippe C8e9a ey in-or" porated# te;t"para<rap8s rep8rased# e;" a7p es strea7 ined# new ru es and re-" o77endations added. In-orporated C?? -8apter fro7 ,. Siebert. Added @)ationa eA se-tions to 7any ru es. ,or7attin< of e;a7p es -orre-ted. %ew ru es and re-o77enda" tions added. ,irst issue
0 0 0 0
2 ( 4 5
0260262004 1=60(62004 2!60562004 (060>62004
>
0>61262004
'
1(60162005
0 1
! 0
0260=62005 0(60(62005
$ar-8 2005 " Board for Software Standardisation and Contro $. Spada and :"2 0errai on# BSSC Co"-8air Copyri<8t B 2005 by European Spa-e A<en-y
BSSC 2005(2) Issue 1.0 0AB2E ., C.%0E%0S
iii
Table of Contents
Document Status Sheet ....................................................................................................... ii Table of Contents ................................................................................................................ iii List of Rules ......................................................................................................................... vi List of Recommendations ................................................................................................. !reface ............................................................................................................................... ii vi
Chapter " #ntroduction ........................................................................................................................ "$ 1.1 1.2 1' 1.( 1.4 1.5 S-ope and App i-abi ity 1' Position of t8is do-u7ent wit8 respe-t to t8e ECSS"E40 and ECSS"C!0 Standards *o-u7ent .9er9iew 5 ossary A-rony7s 1! 1! 24
Chapter % #nstallation& 'uild and (pdates ........................................................................................ %) 2.1 2.2 2.( 2.4 2.5 Introdu-tion Apa-8e Ant Preferen-es Software *istribution I7p e7entation ,i es 2> 2> 2> 2' 2'
Chapter * Source Code Structure ...................................................................................................... %+ (.1 (.2 (.( (.4 (.5 I7p e7entation ,i es 5enera Code Indentation )u es *efinitions State7ents B an& 2ines and Spa-es 2! 2= (1 (2 (>
Chapter , -aming ................................................................................................................................ *. 4.1 4.2 4.( Introdu-tion 5enera %a7in< Con9entions Pa-&a<e %a7es (= (= 41
BSSC 2005(2) Issue 1.0 0AB2E ., C.%0E%0S 4.4 4.5 4.> 4.>.1 4.>.2 4.' 0ype# C ass and Interfa-e %a7es $et8od %a7es 3ariab e %a7es Para7eter %a7es Instan-e 3ariab e %a7es Constant %a7es
i9
42 44 45 4> 4> 4'
Chapter / Documentation and Commenting Conventions .............................................................. ,+ 5.1 5.2 5.( 5.4 5.5 5.> 5.' Introdu-tion Co77ent 0ypes *o-u7entin< t8e *etai ed *esi<n :a9ado- 5enera *es-riptions :a9ado- Co77ents Co77ent Contents and Sty e Interna Co77ents 4! 4! 4! 4= 4= 52 5(
Chapter ) Java Design and !rogramming 0uidelines ..................................................................... // >.1 >.2 >.( >.4 >.5 >.> >.' >.! >.= >.10 Introdu-tion Pa-&a<es 5enera C ass 5uide ines %ested C asses# Inner C asses# and Anony7ous C asses Constru-tors and .bDe-t 2ife-y- e $et8ods 2o-a 3ariab es and E;pressions 5eneri-s and Castin< Constants and Enu7erated 0ypes 08read Syn-8roniEation Issues 55 55 5! >2 >( >> >' >! '0 '2
Chapter $ Robustness ......................................................................................................................... $$ '.1 '.2 '.( '.4 '.5 '.> Introdu-tion *esi<n by Contra-t Assertions *ebu<<in< E;-eptions and Error 1and in< 0ype Safety '' '' '! '= '= !2
Chapter + !ortability ............................................................................................................................ +* !.1 !.2 Introdu-tion )u es !( !(
Chapter . Real1Time Java ................................................................................................................... .2
BSSC 2005(2) Issue 1.0 0AB2E ., C.%0E%0S =.1 =.2 =.( =.4 =.5 Introdu-tion A %ote on Auto7ati- 5arba<e Co e-tion Soft )ea "0i7e *e9e op7ent 5uide ines 1ard )ea "0i7e *e9e op7ent 5uide ines Safety"Criti-a *e9e op7ent 5uide ines
=0 =0 =1 =4 ==
Chapter "2 3mbedding C44 or C in Java .......................................................................................... "2% 10.1 10.2 10.( 10.4 10.5 10.> Introdu-tion A ternati9es to :%I Safety Perfor7an-e 2ow 2e9e 1ardware A--ess %on"Standard %ati9e Interfa-es 102 102 10( 104 10' 10'
Chapter "" Security ............................................................................................................................. "2+ 11.1 11.2 11.( 11.4 11.5 11.> 11.' Introdu-tion 08e :a9a Se-urity ,ra7ewor& Pri9i e<ed Code Se-ure Codin< Seria iEation %ati9e $et8ods and Se-urity 1and in< Sensiti9e Infor7ation 10! 10! 10! 110 110 111 112
'ibliography....................................................................................................................... ""*
BSSC 2005(2) Issue 1.0 2IS0 ., )/2ES
9i
List of Rules
)u e 1: /se t8e Apa-8e Ant too to auto7ati-a y bui d your proDe-t. .................................. 2> )u e 2: F8en distributin< a proDe-t# pa-&a<e a ne-essary - ass and resour-e fi es in a Dar fi e. ........................................................................................................................................ 2' )u e (: *efine on y one - ass or interfa-e per .Da9a fi e. ...................................................... 2' )u e 4: /se t8e fo owin< stru-ture for a i7p e7entation fi es: .......................................... 2! )u e 5: *o not use tab -8ara-ters in i7p e7entation fi es# use p ain spa-es instead. ........ 2= )u e >: /se t8e fo owin< order to de- are 7e7bers of a - ass: ......................................... 2= )u e ': /se four spa-es of indentation. ............................................................................... 2= )u e !: ,or7at - ass and interfa-e definitions a--ordin< to t8e fo owin< 7ode : ............... (1 )u e =: Put sin< e 9ariab e definitions in separate ines. ...................................................... (2 )u e 10: Put sin< e state7ents in separate ines. ................................................................ (2 )u e 11: ,or7at -o7pound state7ents a--ordin< to t8e fo owin< <uide ines: ................... (2 )u e 12: A ways put bra-es around state7ents -ontained in -ontro stru-tures. ................ (( )u e 1(: ,or7at if"e se state7ents a--ordin< to t8e fo owin< 7ode s: .............................. (( )u e 14: ,or7at for state7ents a--ordin< to t8e fo owin< 7ode : ...................................... (4 )u e 15: ,or7at w8i e state7ents a--ordin< to t8e fo owin< 7ode : .................................. (4 )u e 1>: ,or7at do"w8i e state7ents a--ordin< to t8e fo owin< 7ode : ............................. (5 )u e 1': ,or7at swit-8 state7ents a--ordin< to t8e fo owin< 7ode : ................................ (5 )u e 1!: ,or7at try"-at-8 state7ents a--ordin< to t8e fo owin< 7ode : ............................ (5 )u e 1=: 2ea9e two b an& ines: ........................................................................................... (> )u e 20: 2ea9e one b an& ine: ............................................................................................. (> )u e 21: A ways use a spa-e -8ara-ter: .............................................................................. (' )u e 22: /se A7eri-an En< is8 for identifiers. ..................................................................... (= )u e 2(: )estri-t identifiers to t8e ASCII -8ara-ter set. ....................................................... (= )u e 24: A9oid na7es t8at differ on y in -ase. ..................................................................... 40 )u e 25: Capita iEe t8e first etter of standard a-rony7s. .................................................... 41 )u e 2>: *o not 8ide de- arations. ....................................................................................... 41 )u e 2': /se t8e re9ersed# ower"-ase for7 of your or<aniEationGs Internet do7ain na7e as t8e root Hua ifier for your pa-&a<e na7es. ......................................................................... 41 )u e 2!: /se a sin< e# ower"-ase word as t8e root na7e of ea-8 pa-&a<e. ...................... 42
BSSC 2005(2) Issue 1.0 2IS0 ., )/2ES
9ii
)u e 2=: Capita iEe t8e first etter of ea-8 word t8at appears in a - ass or interfa-e na7e. ..... 42 )u e (0: /se nouns or adDe-ti9es w8en na7in< interfa-es. ................................................ 42 )u e (1: /se nouns w8en na7in< - asses. ......................................................................... 4( )u e (2: P ura iEe t8e na7es of - asses t8at <roup re ated attributes# stati- ser9i-es or -on" stants. ................................................................................................................................... 4( )u e ((: /se ower"-ase for t8e first word and -apita iEe on y t8e first etter of ea-8 subse" Huent word t8at appears in a 7et8od na7e. ....................................................................... 44 )u e (4: /se 9erbs in i7perati9e for7 to na7e 7et8ods t8at: ............................................ 44 )u e (5: /se 9erbs in present t8ird person to na7e ana yEer 7et8ods returnin< a boo ean 9a ue. .................................................................................................................................... 44 )u e (>: /se nouns to na7e ana yEer 7et8ods returnin< a non"boo ean 9a ue# or# a terna" ti9e y# na7e t8e7 usin< t8e 9erb @<etA. ................................................................................ 45 )u e (': %a7e 7et8ods settin< properties of an obDe-t (set 7et8ods) usin< t8e 9erb @setA. .. 45 )u e (!: /se nouns to na7e 9ariab es and attributes. ........................................................ 45 )u e (=: F8en a -onstru-tor or @setA 7et8od assi<ns a para7eter to a fie d# <i9e t8at pa" ra7eter t8e sa7e na7e as t8e fie d. ................................................................................... 4> )u e 40: Cua ify instan-e 9ariab e referen-es wit8 t8is to distin<uis8 t8e7 fro7 o-a 9ari" ab es. .................................................................................................................................... 4> )u e 41: /se upper"-ase etters for ea-8 word and separate ea-8 pair of words wit8 an un" ders-ore w8en na7in< :a9a -onstants. ............................................................................... 4' )u e 42: Pro9ide a su77ary des-ription and o9er9iew for ea-8 app i-ation or <roup of pa-&" a<es. ..................................................................................................................................... 4= )u e 4(: Pro9ide a su77ary des-ription and o9er9iew for ea-8 pa-&a<e. ......................... 4= )u e 44: /se do-u7entation -o77ents to des-ribe t8e pro<ra77in< interfa-e. ............... 4= )u e 45: *o-u7ent pub i-# prote-ted# pa-&a<e# and pri9ate 7e7bers. .............................. 50 )u e 4>: /se a sin< e -onsistent for7at and or<aniEation for a do-u7entation -o77ents. .. 50 )u e 4': Frap &eywords# identifiers# and -onstants 7entioned in do-u7entation -o77ents wit8 I-odeJ...I6-odeJ ta<s. ................................................................................................. 50 )u e 4!: Frap fu -ode e;a7p es appearin< in do-u7entation -o77ents wit8 IpreJ ... I6preJ ta<s. .......................................................................................................................... 51 )u e 4=: In- ude :a9ado- ta<s in a -o77ent in t8e fo owin< order: ................................... 51 )u e 50: In- ude an Kaut8or and a K9ersion ta< in e9ery - ass or interfa-e des-ription. . 51 )u e 51: ,u y des-ribe t8e si<nature of ea-8 7et8od. ........................................................ 52 )u e 52: *o-u7ent syn-8roniEation se7anti-s. .................................................................. 5( )u e 5(: Add a @fa "t8rou<8A -o77ent between two -ase abe s# if no brea& state7ent sepa" rates t8ose abe s. ................................................................................................................ 5( )u e 54: 2abe e7pty state7ents. ....................................................................................... 54 )u e 55: /se end" ine -o77ents to e;p i-it y 7ar& t8e o<i-a ends of -onditiona s oops# e;" -eptions# enu7erations# 7et8ods or - asses. ...................................................................... 54
BSSC 2005(2) Issue 1.0 2IS0 ., )/2ES
9iii
)u e 5>: *o not use t8e wi d-ard (@LA) notation in i7port state7ents. ................................. 5' )u e 5': Put a s8ared - asses and interfa-es t8at are interna to a proDe-t in a separate pa-&a<e -a ed @interna A. ..................................................................................................... 5' )u e 5!: $a&e - asses t8at do not be on< to a pa-&a<eMs pub i- API pri9ate. ..................... 5! )u e 5=: $a&e a - ass attributes pri9ate. ........................................................................... 5! )u e >0: A - ass s8a define at east one -onstru-tor. ........................................................ >( )u e >1: 1ide any -onstru-tors t8at do not -reate 9a id instan-es of t8e -orrespondin< - ass# by de- arin< t8e7 as prote-ted or pri9ate. ........................................................................... >( )u e >2: *o not -a non"fina 7et8ods fro7 wit8in a -onstru-tor. ...................................... >( )u e >(: $et8ods t8at do not 8a9e to a--ess instan-e 9ariab es s8a be de- ared stati-. . >> )u e >4: A para7eter t8at is not -8an<ed by t8e 7et8od s8a be de- ared fina . .............. >> )u e >5: /se parent8eses to e;p i-it y indi-ate t8e order of e;e-ution of nu7eri-a operators . ............................................................................................................................................ >! )u e >>: /se <eneri-s instead of -astin< w8en na9i<atin< t8rou<8 -o e-tions. ................. >= )u e >': Preser9e 7et8od -ontra-ts in deri9ed - asses. ..................................................... '! )u e >!: E;p i-it y -8e-& 7et8od para7eters for 9a idity# and t8row an adeHuate e;-eption in -ase t8ey are not 9a id. *o not use t8e assert state7ent for t8is purpose. ..................... '! )u e >=: Add dia<nosti- -ode to a areas t8at# a--ordin< to t8e e;pe-tations of t8e pro<ra7" 7er# s8ou d ne9er be rea-8ed. ............................................................................................ '= )u e '0: *o not use e;pressions wit8 side effe-ts as ar<u7ents to t8e assert state7ent. ..... '= )u e '1: /se t8e :a9a o<<in< 7e-8anis7 for a debu<<in< state7ents instead of resortin< to t8e Syste7.out.print n fun-tion. ........................................................................................ '= )u e '2: /se un-8e-&ed# run"ti7e e;-eptions to 8and e serious une;pe-ted abnor7a situa" tions# in- udin< t8ose t8at 7ay indi-ate errors in t8e pro<ra7Gs o<i-. ................................ !0 )u e '(: /se -8e-&ed e;-eptions to report errors t8at 7ay o--ur# e9en if rare y# under nor" 7a pro<ra7 operation. ........................................................................................................ !0 )u e '4: *o not si ent y absorb a run"ti7e or error e;-eption. ............................................ !1 )u e '5: %e9er i<nore error 9a ues reported by 7et8ods. ................................................... !2 )u e '>: *o not re y on t8read s-8edu in< parti-u arities to define t8e be8a9ior of your pro" <ra7# use syn-8roniEation instead. ...................................................................................... !( )u e '': A9oid nati9e 7et8ods. ........................................................................................... !4 )u e '!: )estri-t t8e use of t8e Syste7.e;it 7et8od to t8e -ases des-ribed be ow. .......... !5 )u e '=: *o not 8ard"-ode fi e na7es and pat8s in your pro<ra7. ..................................... !> )u e !0: A ways 7a&e :*BC dri9er na7es -onfi<urab e# do not 8ard -ode t8e7. ............. !> )u e !1: *o not re y on a parti-u ar -on9ention for ine ter7ination. ................................... !> )u e !2: )estri-t t8e use of Syste7.in# Syste7.out or Syste7.err to pro<ra7s e;p i-it y in" tended for t8e -o77and ine. .............................................................................................. !' )u e !(: F8en ne-essary# use t8e internationa iEation and o-a iEation features of t8e :a9a p atfor7. ............................................................................................................................... !' )u e !4: *o not 8ard -ode position and siEes of <rap8i-a e e7ents. ................................. !!
BSSC 2005(2) Issue 1.0 2IS0 ., )/2ES
i;
)u e !5: *o not 8ard -ode te;t siEes or font na7es. ........................................................... !! )u e !>: *o not 8ard -ode -o ors or ot8er 5/I appearan-e e e7ents. ............................... !! )u e !': *o not retain 5rap8i-s obDe-ts passed to update 7et8ods of <rap8i-a -o7po" nents. ................................................................................................................................... !! )u e !!: *o not use 7et8ods 7ar&ed as depre-ated in t8e :a9a API. ............................... != )u e !=: *o not re y on t8e for7at of t8e resu t of t8e Da9a.net.InetAddress.<et1ost%a7e 7et8od. ................................................................................................................................ != )u e =0: A ways -8e-& for o-a a9ai abi ity of P u<<ab e 2oo& and ,ee (P2A,) - asses# and pro9ide a safe fa ba-& in -ase t8ey are not a9ai ab e. ....................................................... != )u e =1: *o not 7i; - asses -o7pi ed a<ainst different 9ersions of t8e :a9a p atfor7. ...... != )u e =2: /se t8e :a9a 2 Standard Edition (:2SE) p atfor7. ................................................ =1 )u e =(: Base ine a parti-u ar 9ersion of t8e :2SE ibraries. ............................................... =1 )u e =4: /se -ooperatin< 8ard rea "ti7e -o7ponents to interfa-e wit8 nati9e -ode. .......... =1 )u e =5: /se -ooperatin< 8ard rea "ti7e -o7ponents to i7p e7ent perfor7an-e"-riti-a -ode. ..................................................................................................................................... =2 )u e =>: /se -ooperatin< 8ard rea "ti7e -o7ponents to intera-t dire-t y wit8 8ardware de" 9i-es. .................................................................................................................................... =2 )u e =': Iso ate :3$ dependen-ies. .................................................................................... =2 )u e =!: /se a 8ard rea "ti7e subset of t8e standard :a9a ibraries. .................................. =4 )u e ==: /se a 8ard rea "ti7e subset of t8e rea "ti7e spe-ifi-ation for :a9a. ..................... =4 )u e 100: /se en8an-ed rep a-e7ents for -ertain )0S: ibraries. ..................................... =5 )u e 101: Assure a9ai abi ity of supp e7enta ibraries. ....................................................... =5 )u e 102: /se an inte i<ent in&er and annotations to <uide initia iEation of stati- 9ariab es. .. =5 )u e 10(: /se on y 12! priority e9e s for %o1eap)ea ti7e08read. .................................... => )u e 104: *o not instantiate Da9a. an<.08read or Da9a;.rea ti7e.)ea ti7e08read. ............. => )u e 105: Prea o-ate 08rowab e instan-es. ........................................................................ => )u e 10>: )estri-t a--ess to 08rowab e attributes. .............................................................. => )u e 10': Annotate a pro<ra7 -o7ponents to Indi-ate s-oped 7e7ory be8a9iors. ........ => )u e 10!: Carefu y restri-t use of 7et8ods de- ared wit8 KA owC8e-&edS-oped2in&s an" notation. ................................................................................................................................ =' )u e 10=: Carefu y restri-t use of 7et8ods de- ared wit8 KI77orta A o-ation annotation. .. =' )u e 110: /se KStati-Ana yEab e annotation to identify 7et8ods wit8 bounded resour-e needs. ................................................................................................................................... =' )u e 111: /se 8ierar-8i-a or<aniEation of 7e7ory to support software 7odu es. ............. =! )u e 112: /se t8e K0raditiona :a9aS8ared -on9entions to s8are obDe-ts wit8 traditiona :a" 9a. ......................................................................................................................................... =! )u e 11(: A9oid syn-8roniEed state7ents. .......................................................................... =!
BSSC 2005(2) Issue 1.0 2IS0 ., )/2ES
)u e 114: In8erit fro7 PCP in any - ass t8at uses PriorityCei in<E7u ation $onitorContro po i-y. ................................................................................................................................... =! )u e 115: In8erit fro7 Ato7i- in any - ass t8at syn-8roniEes wit8 interrupt 8and ers. ........ =! )u e 11>: Annotate t8e -ei in<Priority() 7et8od of Ato7i- and PCP - asses wit8 KCei in<. ... =! )u e 11': *o not o9erride .bDe-t.fina iEe(). ......................................................................... == )u e 11!: E;-ept w8ere indi-ated to t8e -ontrary# use 8ard rea "ti7e pro<ra77in< <uide" ines. ..................................................................................................................................... == )u e 11=: /se on y 2! priority e9e s for %o1eap)ea ti7e08read. ...................................... == )u e 120: Pro8ibit use of K.7itSubs-riptC8e-&in< annotation. ........................................ == )u e 121: Pro8ibit in9o-ation of 7et8ods de- ared wit8 KA owC8e-&edS-oped2in&s anno" tation. .................................................................................................................................... == )u e 122: )eHuire a -ode to be KStati-Ana yEab e. ....................................................... 100 )u e 12(: )eHuire a - asses wit8 Syn-8roniEed 7et8ods to in8erit PCP or Ato7i-. ....... 100 )u e 124: Pro8ibit dyna7i- - ass oadin<. ......................................................................... 100 )u e 125: Pro8ibit use of b o-&in< ibraries. ....................................................................... 100 )u e 12>: Pro8ibit use of PriorityIn8eritan-e $onitorContro po i-y. .................................. 100 )u e 12': *o not s8are safety"-riti-a obDe-ts wit8 a traditiona :a9a 9irtua 7a-8ine. ..... 101 )u e 12!: /se t8e estab is8ed -odin< standards for C?? or C for t8e de9e op7ent of C?? or C -ode t8at is e7bedded into t8e :a9a -ode. .................................................................... 10( )u e 12=: C8e-& for E;-eption.--urred() after ea-8 -a of a fun-tion in t8e :%I interfa-e if t8at 7ay -ause an e;-eption. ............................................................................................ 10( )u e 1(0: $ar& nati9e 7et8ods as pri9ate. ........................................................................ 10( )u e 1(1: Se e-t 7et8od na7es for C?? or C 7et8ods t8at state - ear y t8at su-8 a 7et8od is a nati9e 7et8od. ............................................................................................................. 104 )u e 1(2: A9oid na7e o9er oadin< for nati9e 7et8ods. .................................................... 104 )u e 1((: *o not use wea& < oba referen-es. .................................................................. 104 )u e 1(4: /se *e ete2o-a )ef() to free referen-es in nati9e -ode t8at were obtained in a oop. .................................................................................................................................... 105 )u e 1(5: /se %ew5 oba )ef()6*e ete5 oba )ef() on y for referen-es t8at are stored outside of rea-8ab e 7e7ory t8at sur9i9es fro7 one :%I -a to t8e ne;t. ..................................... 105 )u e 1(>: A9oid usin< :%I for nati9e 1F a--ess if a ternati9e 7eans are a9ai ab e. ........ 10' )u e 1(': *o not use non"standard nati9e interfa-es un ess t8ere are 9ery <ood reasons to do so. .................................................................................................................................. 10' )u e 1(!: )estri-t t8e use of non"standard nati9e interfa-e uses to as few fun-tions as pos" sib e. ................................................................................................................................... 10' )u e 1(=: )efrain fro7 usin< non"fina pub i- stati- 9ariab es. .......................................... 110 )u e 140: %e9er return referen-es to interna 7utab e obDe-ts -ontainin< sensiti9e data. ....... 110 )u e 141: %e9er store user pro9ided 7utab e obDe-ts dire-t y. ......................................... 110
BSSC 2005(2) Issue 1.0 2IS0 ., )/2ES
;i
)u e 142: /se t8e transient &eyword for fie ds t8at -ontain dire-t 8and es to syste7 re" sour-es# or t8at -ontain infor7ation re ati9e to an address spa-e. ................................... 111 )u e 14(: *efine - ass spe-ifi- seria iEin<6deseria iEin< 7et8ods. .................................... 111 )u e 144: F8i e deseria iEin< an obDe-t of a parti-u ar - ass# use t8e sa7e set of restri-tions used w8i e -reatin< obDe-ts of t8e - ass. ............................................................................ 111 )u e 145: E;p i-it y - ear sensiti9e infor7ation fro7 7ain 7e7ory. .................................. 112 )u e 14>: A ways store sensiti9e infor7ation in 7utab e data stru-tures. ......................... 112
BSSC 2005(2) Issue 1.0 2IS0 ., )EC.$$E%*A0I.%S
;ii
List of Recommendations
)e-o77endation 1: /se t8e Ant too to auto7ate as 7any additiona proDe-t tas&s as possi" b e. ........................................................................................................................................ 2> )e-o77endation 2: /se t8e :a9a Preferen-es API to store and retrie9e a run"ti7e -onfi<" uration data. ......................................................................................................................... 2> )e-o77endation (: /se a standard te7p ate or uti ity pro<ra7 to pro9ide a startin< point for i7p e7entation fi es. ............................................................................................................ 2! )e-o77endation 4: A9oid ines on<er t8an !0 -8ara-ters. ............................................... (0 )e-o77endation 5: F8en brea&in< on< ines# fo ow t8ese <uide ines: ............................ (0 )e-o77endation >: A9oid parent8eses around t8e return 9a ues of return state7ents. ... (> )e-o77endation ': Separate <roups of state7ents in a 7et8od usin< sin< e b an& ines. .... (' )e-o77endation !: Pi-& identifiers t8at a--urate y des-ribe t8e -orrespondin< pro<ra7 en" tity. ........................................................................................................................................ (= )e-o77endation =: /se ter7ino o<y app i-ab e to t8e do7ain. ......................................... 40 )e-o77endation 10: A9oid on< (e.<. 7ore t8an 20 -8ara-ters) identifiers. ...................... 40 )e-o77endation 11: /se abbre9iations sparin< y and -onsistent y. .................................. 40 )e-o77endation 12: /se do-u7entation -o77ents to des-ribe pro<ra77in< interfa-es before i7p e7entin< t8e7. .................................................................................................. 4! )e-o77endation 1(: Consider 7ar&in< t8e first o--urren-e of an identifier wit8 a NK in&O ta<. ....................................................................................................................................... 51 )e-o77endation 14: *o-u7ent pre-onditions# post -onditions# and in9ariant -onditions. ..... 52 )e-o77endation 15: In- ude e;a7p es. ............................................................................. 5( )e-o77endation 1>: /se @t8isA rat8er t8an @t8eA w8en referrin< to instan-es of t8e -urrent - ass. .................................................................................................................................... 5( )e-o77endation 1': *o-u7ent o-a 9ariab es wit8 an end" ine -o77ent. ...................... 5( )e-o77endation 1!: /se separate pa-&a<es for ea-8 of t8e software -o7ponents defined durin< t8e desi<n p8ase. ...................................................................................................... 55 )e-o77endation 1=: P a-e into t8e sa7e pa-&a<e types t8at are -o77on y used# -8an<ed# and re eased to<et8er# or 7utua y dependent on ea-8 ot8er. ............................ 55 )e-o77endation 20: A9oid -y- i- pa-&a<e dependen-ies. ................................................ 5> )e-o77endation 21: Iso ate 9o ati e - asses and interfa-es in separate pa-&a<es. .......... 5>
;iii
)e-o77endation 22: A9oid 7a&in< pa-&a<es t8at are diffi-u t to -8an<e dependent on pa-&a<es t8at are easy to -8an<e. ...................................................................................... 5> )e-o77endation 2(: $a;i7iEe abstra-tion to 7a;i7iEe stabi ity. ...................................... 5> )e-o77endation 24: Capture 8i<8" e9e desi<n and ar-8ite-ture as stab e abstra-tions or" <aniEed into stab e pa-&a<es. .............................................................................................. 5' )e-o77endation 25: Consider usin< :a9a interfa-es instead of - asses for t8e pub i- API of a pa-&a<e. ............................................................................................................................ 5! )e-o77endation 2>: Consider de- arin< - asses representin< funda7enta data types as fi" na . ........................................................................................................................................ 5= )e-o77endation 2': .)edu-e t8e siEe of - asses and 7et8ods by refa-torin<. ................ 5= )e-o77endation 2!: A9oid in8eritan-e a-ross pa-&a<esP re y on interfa-e i7p e7entation instead. ................................................................................................................................. 5= )e-o77endation 2=: 2i7it t8e use of anony7ous - asses. ................................................ >2 )e-o77endation (0: A9oid -reatin< unne-essary obDe-ts. ................................................ >( )e-o77endation (1: A9oid usin< t8e new &eyword dire-t y. .............................................. >4 )e-o77endation (2: Consider t8e use of stati- fa-tory 7et8ods instead of -onstru-tors. .... >4 )e-o77endation ((: /se nested -onstru-tors to e i7inate redundant -ode. .................... >4 )e-o77endation (4: /se aEy initia iEation. ........................................................................ >5 )e-o77endation (5: )efrain fro7 usin< t8e instan-eof operator. )e y on po y7orp8is7 in" stead. .................................................................................................................................... >> )e-o77endation (>: /se o-a 9ariab es for one purpose on y. ......................................... >' )e-o77endation (': )ep a-e repeated non"tri9ia e;pressions wit8 eHui9a ent 7et8ods. ..... >' )e-o77endation (!: Consider usin< t8e Strin<Buffer - ass w8en -on-atenatin< strin<s. ..... >' )e-o77endation (=: /se t8e en8an-ed for -ontro stru-ture and <eneri-s w8ere9er possi" b e6app i-ab e. ...................................................................................................................... >! )e-o77endation 40: Be -arefu w8en usin< t8e i7port stati- feature to define < oba -on" stants. ................................................................................................................................... '0 )e-o77endation 41: /se type"safe enu7erations as defined usin< t8e enu7 &eyword. .. '1 )e-o77endation 42: /se t8reads on y w8ere appropriate. ................................................ '2 )e-o77endation 4(: )edu-e syn-8roniEation to t8e 7ini7u7 possib e. .......................... '2 )e-o77endation 44: *o not syn-8roniEe an entire 7et8od if t8e 7et8od -ontains si<nifi" -ant operations t8at do not need syn-8roniEation. .............................................................. '2 )e-o77endation 45: A9oid unne-essary syn-8roniEation w8en readin< or writin< instan-e 9ariab es. .............................................................................................................................. '( )e-o77endation 4>: /se syn-8roniEed wrappers to pro9ide syn-8roniEed interfa-es. ..... '4 )e-o77endation 4': Consider usin< notify() instead of notifyA (). .................................... '5 )e-o77endation 4!: /se t8e doub e"-8e-& pattern for syn-8roniEed initia iEation. ........... '5 )e-o77endation 4=: *efine 7et8od -ontra-ts and enfor-e t8e7. .................................... ''
;i9
)e-o77endation 50: F8ene9er possib e# a 7et8od s8ou d eit8er return t8e resu t spe-ified by its -ontra-t# or t8row an e;-eption w8en t8at is not possib e. ......................................... '! )e-o77endation 51: )e y on :a9aMs assert state7ent to e;p i-it y -8e-& for pro<ra77in< errors in your -ode. .............................................................................................................. '! )e-o77endation 52: F8ene9er possib e# use fina y b o-&s to re ease resour-es. ........... !1 )e-o77endation 5(: .n y -on9ert e;-eptions to add infor7ation. .................................... !1 )e-o77endation 54: En-apsu ate enu7erations as - asses. ............................................ !2 )e-o77endation 55: F8ene9er possib e# prefer t8e Swin< API to t8e o d AF0 API for de" 9e opin< <rap8i-a user interfa-es. ...................................................................................... !( )e-o77endation 5>: *o not use t8e Da9a. an<.)unti7e.e;e- 7et8od. ............................. !5 )e-o77endation 5': *o not 8ard"-ode disp ay attributes# i&e position and siEe for <rap8i-a e e7ent# te;t font types and siEes# -o ors# ayout 7ana<e7ent detai s# et-. ....................... !5 )e-o77endation 5!: C8e-& a uses of t8e :a9a ref e-tion features for indire-t in9o-ation of 7et8ods t8at 7ay -ause portabi ity prob e7s. ..................................................................... !5 )e-o77endation 5=: )e y on t8e wide y &nown P.SI+ -on9entions to define t8e synta; of your -o77and ine options. ................................................................................................. !' )e-o77endation >0: )estri-t t8e use of non ASCII -8ara-ters in your 7essa<es to t8e 7in" i7u7 possib e. ..................................................................................................................... !' )e-o77endation >1: Consider usin< :,a-e and SF0 for 5rap8i-a /ser Interfa-es. ...... =1 )e-o77endation >2: )estri-t t8e use of ad9an-ed ibraries. ............................................. =2 )e-o77endation >(: Carefu y se e-t an appropriate soft rea "ti7e 9irtua 7a-8ine. ......... =( )e-o77endation >4: /se de9e op7ent too s to enfor-e -onsisten-y wit8 8ard rea "ti7e <uide ines. ............................................................................................................................ == )e-o77endation >5: /se de9e op7ent too s to enfor-e -onsisten-y wit8 safety"-riti-a <uide ines. .......................................................................................................................... 101 )e-o77endation >>: A9oid e7beddin< C?? or C -ode in :a9a as 7u-8 as possib e. /se ot8er -oup in< so utions instead if C?? or C -ode needs to be inte<rated to t8e software produ-t. .............................................................................................................................. 102 )e-o77endation >': A9oid t8e use of C?? or C -ode e7bedded usin< t8e :%I to in-rease perfor7an-e. ...................................................................................................................... 105 )e-o77endation >!: A9oid passin< referen-e 9a ues to nati9e -ode. ............................. 105 )e-o77endation >=: A9oid -a in< ba-& into :a9a -ode fro7 C6C?? -ode. ..................... 10> )e-o77endation '0: Put as 7u-8 fun-tiona ity as possib e into t8e :a9a -ode and as itt e as possib e in t8e :%I -ode. ............................................................................................... 10> )e-o77endation '1: A9oid 5etLArrayE e7ents() and 5etLArrayE e7entsCriti-a () fun-tions. ............................................................................................................................................ 10> )e-o77endation '2: A9oid freHuent -a s to t8e ref e-ti9e fun-tions ,indC ass()# 5et$et8o" dI*()# 5et,ie dI*()# and 5etStati-,ie dI*(). ....................................................................... 10> )e-o77endation '(: Qeep pri9i e<ed -ode as s8ort as possib e. .................................... 10= )e-o77endation '4: C8e-& a uses of tainted 9ariab es in pri9i e<ed -ode. ................... 10= )e-o77endation '5: )edu-e t8e s-ope of 7et8ods as 7u-8 as possib e. ..................... 110 )e-o77endation '>: Consider en-ryptin< seria iEed byte strea7s. ................................. 111
;9
)e-o77endation '': C8e-& nati9e 7et8ods before re ayin< on t8e7 for pri9i e<ed -ode. .... 111
BSSC 2005(2) Issue 1.0 P)E,ACE
;9i
!reface
08is Codin< Standard is based upon t8e e;perien-e of de9e opin< -usto7 spa-e syste7 software usin< t8e :a9a pro<ra77in< an<ua<e. Bot8 pub is8ed e;pe" rien-e and best pra-ti-e ru es obtained by Industry or by 7eans of in"8ouse de9e op" 7ents are in- uded. 08e BSSC wis8es to t8an& t8e European Spa-e )esear-8 and 0e-8no o<y Centre (ES0EC)# %oordwiD&# 08e %et8er ands# and in parti-u ar Peter C aes# for preparin< t8e standard. 08e BSSC a so t8an& a t8ose w8o -ontributed ideas for t8is standard# in parti-u ar *r Qe 9in %i sen ()60 -8apter) and *r :a7es 1unt# *r ,ridtDof Siebert ()60 -8apter and C6C?? inte<ration -8apter). 08e BSSC 7e7bers t8at 8a9e re9iewed t8e standard: $arie a Spada# $i-8ae :ones# :ean"2oup 0errai on# :ean Pierre 5ui<nard# :ero7e *u7as# *anie PonE# *anie de Pab o and 2ot8ar FinEer. 08e BSSC a so wis8es to t8an& t8e fo owin< ESA re9iewers of t8is standard: :on Bru7fitt# A. Bonfie # ,ernando A dea $ontero# 1ans )anebo# :ean"Pas-a 2eDau t# :ose 1ernandeE# :ose PiEarro# P8i ippe C8e9a ey# 3i-ente %a9arro# and t8e e;pert re9iewer# editor# $artin Soto# fro7 Fraunhofer Institute for Experimental software Engineering (IESE). )eHuests for - arifi-ations# -8an<e proposa s or any ot8er -o77ents -on-ern" in< t8is standard s8ou d be addressed to: BSSC6ES.C Se-retariat Attention of $s $. Spada ES.C )obert Bos-8 Strasse 5 *">42=( *ar7stadt 5er7any BSSC6ES0EC Se-retariat Attention of $r :."2. 0errai on ES0EC Postbus 2== %2"2200 A5 %oordwiD& 08e %et8er ands
BSSC 2005(2) Issue 1.0 C1AP0E) 1 I%0).*/C0I.%
1'
Chapter " #ntroduction

"." Scope and 5pplicability
08ese standards present ru es and re-o77endations about t8e use of t8e an" <ua<e -onstru-ts of :a9a. $any boo&s and do-u7ents des-ribe 8ow t8ese features -an be used. 08ese te;ts usua y des-ribe w8at is possib e and not ne-essari y w8at is desirab e or a--eptab e# espe-ia y for ar<e software en<ineerin< proDe-ts intend" ed for 7ission" or safety"-riti-a syste7s. 08is do-u7ent is 9a id for t8e :a9a 2 95.0 standard spe-ifi-ation (:2SE 5.0.;) as we as for t8e :a9a )ea "0i7e Spe-ifi-ation R)0S:S as pub is8ed by t8e :a9a )ea "0i7e E;perts 5roup. 08is do-u7ent pro9ides a set of <uide ines for pro<ra77in< in :a9a w8i-8 are intended to i7pro9e t8e o9era Hua ity and 7aintainabi ity of software de9e oped by# or under -ontra-t to# t8e European Spa-e A<en-y. 08e use of t8is standard s8ou d i7pro9e -onsisten-y a-ross different software syste7s de9e oped by different pro" <ra77in< tea7s in different -o7panies or de9e oped in"8ouse in t8e A<en-y. 08e <uide ines in t8is standard s8ou d be 7et for :a9a sour-e -ode to fu y -o7" p y wit8 t8is standard. 08e standard 8as no -ontra-tua i7p i-ation. Contra-tua ob i" <ations are <i9en in indi9idua proDe-t do-u7ents. 08is do-u7ent is in prin-ip e a referen-e do-u7ent. As wit8 ot8er BSSC -odin< standards# proDe-t 7ana<ers 7ay de-ide to 7a&e it app i-ab e# parti-u ar y in t8e -ase t8at a supp ier does not 8a9e a suitab e in"8ouse standard. 08e readers are e;pe-ted to be :a9a pro<ra77ers (re ated to# or doin< wor& for ESA) t8at understand 9ery we t8e wor&in<s of t8e an<ua<e. *is- ai7er: Pro<ra7s and -ode snippets presented in t8is do-u7ent are by no 7eans <uaranteed to be usab e as runnab e -ode. 08ey are on y in- uded to de7onstrate -on-epts out ined in t8e ru es and <uide ines.
".%
!osition of this document 6ith respect to the 3CSS13,2 and 3CSS17+2 Standards
08e ECSS bund e of standards is or<aniEed around fa7i ies. In parti-u ar# t8e En<ineerin< fa7i y 8as a dedi-ated nu7ber for software (40)# and t8e Cua ity fa7i y 8as a dedi-ated nu7ber for software produ-t assuran-e (!0). 08e ECSS-E-40 Part 1B, Space Engineering - Software - Part 1 Principles an! re"uirements (appro9ed 2! %o9 200() do-u7ent re-a s t8e 9arious software en<i" neerin< pro-esses and ist reHuire7ents for t8ese pro-esses in ter7s of a-ti9ities t8at 8a9e to be perfor7ed# as we as pie-es of infor7ation t8at 8a9e to be produ-ed. ECSS-E40 1B does not address dire-t y t8e -odin< standards# but reHuires t8at t8e -odin< standards are defined and a<reed# at 9arious e9e s of t8e de9e op7ent# be"
BSSC 2005(2) Issue 1.0 C1AP0E) 1 I%0).*/C0I.% tween t8e -usto7er and t8e supp ier.
1!
In parti-u ar# t8e se e-tion of t8is :a9a standard -ou d be t8e answer to t8e fo " owin< reHuire7ents in t8e ECSS-E40 1B standard: #$%$%$1 S&stem re"uirements specification, Expecte! 'utput !( I!entification of lower le)el software engineering stan!ar!s *+B, S++- .see ECSS- /- 00B su1clauses 2$3$% an! 2$3$3(, A so of re e9an-e# t8e se e-tion of t8is :a9a standard -ou d be t8e answer to t8e fo owin< reHuire7ents of t8e ECSS"C"!0B standard (Software Produ-t Assuran-e# appro9ed 10 .-t 200(): 2$3$3$1 Co!ing stan!ar!s .inclu!ing consistent naming con)entions, an! a!e"uate commentar& rules( shall 1e specifie! an! o1ser)e!$ E4PEC5E6 '75P75 Co!ing stan!ar!s *P8F, P6+-$ 2$3$3$4 Co!ing stan!ar!s shall 1e re)iewe! with the customer to ensure that the& reflect pro!uct "ualit& re"uirements$ E4PEC5E6 '75P75 Co!ing stan!ar!s an! !escription of tools *P8F, P6+-$
".*
Document 8vervie6
08is do-u7ent is intended to bui d on t8e output of t8e Software 5op-9e)el 8rchitectural 6esign# 6esign of Software Items and Co!ing an! 5esting p8ases (ECSS-E-40 ter7ino o<y) and fo ows a Ttop"downT approa-8 so t8at <uide ines -an be<in to be app ied as soon as detai ed desi<n of software ite7s starts and before any -ode is produ-ed. SubseHuent -8apters des-ribe t8e spe-ifi- ru es and re-o7" 7endations to be app ied to t8e produ-tion of :a9a -ode. A ru es (7andatory) and re-o77endations (optiona ) are nu7bered for refer" en-e purposes. A ru es and re-o77endations 8a9e a s8ort tit e and an e;p anation. $any ru es and re-o77endations are a so fo owed by a rationa e se-tion Dustifyin< t8e ap" p i-ation of t8e ru e. )u es and re-o77endations 7ay a so -ontain e;a7p es s8ow" in< 8ow to app y t8e7# or i ustratin< t8e -onseHuen-es of not app yin< t8e7. A ru es and re-o77endations are en- osed in bo;es. )e-o77endations are printed in ita i- type.
".,
0lossary
Abstra-t - ass U A - ass t8at e;ists on y as a super- ass of anot8er - ass and -an ne9er be dire-t y instantiated. In :a9a# an abstra-t - ass -ontains or in8erits one or 7ore abstra-t 7et8ods or in- udes t8e abstract &eyword in its definition. Abstra-tion U 08e pro-ess and resu t of e;tra-tin< t8e -o77on or <enera -8ara-ter" isti-s fro7 a set of si7i ar entities. A--essor U A 7et8od t8at sets or <ets t8e 9a ue of an obDe-t property or attribute. A <orit87 U A finite set of we "defined ru es t8at <i9es a seHuen-e of operations for perfor7in< a spe-ifi- tas&. Ar-8ite-ture U A des-ription of t8e or<aniEation and stru-ture of a software syste7. Ar<u7ent U *ata ite7 spe-ified as a para7eter in a 7et8od -a .
1=
Assertion U A state7ent about t8e trut8 of a o<i-a e;pression. In :a9a# a spe-ia in" stru-tions t8at -8e-&s t8e 9a idity of su-8 a state7ent durin< run"ti7e. Attribute U A feature wit8in a - ass t8at des-ribes a ran<e of 9a ues instan-es of t8e - ass 7ay 8o d. A na7ed -8ara-teristi- or property of a type# - ass# or obDe-t. Be8a9ior U 08e a-ti9ities and effe-ts produ-ed by an obDe-t in response to an e9ent. B o-& state7ent U 08e :a9a an<ua<e -onstru-t t8at -o7bines one or 7ore state" 7ent e;pressions into a sin< e -o7pound state7ent# by en- osin< t8e7 in -ur y bra-es @{...}A. Boo ean U An enu7erated type w8ose 9a ues are true and fa se. Bui t"in type U A data type defined as part of t8e an<ua<e. 08e bui t"in or nati9e types defined by :a9a in- ude t8e pri7iti9e types boolean# byte# char# double# float# int# long# short# and void# and t8e 9arious - asses and interfa-es de" fined in t8e standard :a9a API# su-8 as Object# String# Thread# and so fort8. C8e-&ed e;-eption U Any e;-eption t8at is not deri9ed fro7 java.lang.RuntimeException or java.lang.Error# or t8at appears in t8e throws - ause of a 7et8od. A 7et8od t8at t8rows# or is a re-ipient of# a -8e-&ed e;-eption 7ust 8and e t8e e;-eption interna y or ot8erwise de- are t8e e;-eption in its own throws - ause. C8i d U In a <enera iEation re ations8ip# t8e spe-ia iEation of anot8er e e7ent# t8e parent. C ass U A set of obDe-ts t8at s8are t8e sa7e attributes and be8a9ior. C ient U An entity t8at reHuests a ser9i-e fro7 anot8er entity. Code U 08e i7p e7entation of parti-u ar data or a parti-u ar -o7puter pro<ra7 in a sy7bo i- for7# su-8 as sour-e -ode# obDe-t -ode or 7a-8ine -ode. Code s8arin< U 08e s8arin< of -ode by 7ore t8an one - ass or -o7ponent# e.<. by 7eans of i7p e7entation in8eritan-e or de e<ation. See: i7p e7entation in8eritan-e# de e<ation. Co7pi er U Pro<ra7 t8at trans ates sour-e -ode state7ents of a 8i<8 e9e an<ua<e# su-8 as :a9a# into byte -ode or obDe-t -ode. Co7ponent U (1) A se f"-ontained part# -o7bination of parts# sub"asse7b ies or units# w8i-8 perfor7s a distin-t fun-tion of a syste7. (2) A p8ysi-a # rep a-eab e part of a syste7 t8at pa-&a<es i7p e7entation and pro9ides t8e rea iEation of a set of in" terfa-es. (() A p8ysi-a and dis-rete software entity t8at -onfor7s to a set of inter" fa-es. Co7position U A for7 of a<<re<ation w8ere an obDe-t is -o7posed of ot8er obDe-ts. Con-rete - ass U A - ass t8at -an be dire-t y instantiated. A -on-rete - ass 8as no abstra-t operations. Contrast: abstra-t - ass. Con-urren-y U 08e de<ree by w8i-8 two or 7ore a-ti9ities o--ur or 7a&e pro<ress at t8e sa7e ti7e. 5 oba -onstant U A - ass 9ariab e defined as public static final. Constraint U A se7anti- -ondition or restri-tion. Constraints in- ude pre-onditions# post-onditions# and in9ariants. 08ey 7ay app y to a sin< e - ass of obDe-ts# to re a" tions8ips between - asses of obDe-ts# to states# or to use -ases. Constru-tor U A spe-ia 7et8od t8at initia iEes a new instan-e of a - ass.
BSSC 2005(2) Issue 1.0 C1AP0E) 1 I%0).*/C0I.% Container U An obDe-t w8ose purpose is to -ontain and 7anipu ate ot8er obDe-ts.
20
Contra-t U A - ear des-ription of t8e responsibi ities and -onstraints t8at app y be" tween a - ient and a type# - ass# or 7et8od. C.)BA U An industry wide standard for -o77uni-ation between distributed obDe-ts# independent of t8eir o-ation and tar<et an<ua<e. 08e C.)BA standard is defined by t8e .bDe-t $ana<e7ent 5roup (.$5). C.)BA itse f is an a-rony7 for Co77on .bDe-t )eHuest Bro&er Ar-8ite-ture. Coup in< U 08e de<ree to w8i-8 two or 7ore entities are dependent on ea-8 ot8er. Criti-a software U Software supportin< a safety or dependabi ity -riti-a fun-tion t8at if in-orre-t or inad9ertent y e;e-uted -an resu t in -atastrop8i- or -riti-a -onse" Huen-es. *ata abstra-tion U An abstra-tion denotes t8e essentia -8ara-teristi-s of an obDe-t t8at distin<uis8 it fro7 a ot8er &inds of obDe-ts# suppressin< a non"essentia de" tai s. In data abstra-tion t8e non"essentia detai s dea wit8 t8e under in< data repre" sentation. *atabase U A set of data# part or t8e w8o e of anot8er set of data# -onsistin< of at east one fi e t8at is suffi-ient for a <i9en purpose or for a <i9en data pro-essin< sys" te7. *ata type# U (1) A - ass of data -8ara-teriEed by t8e 7e7bers of t8e - ass and t8e operations t8at -an be app ied to t8e7. E;a7p es are -8ara-ter types and enu7era" tion types. (2) A des-riptor of a set of 9a ues t8at a-& identity and w8ose operations do not 8a9e side effe-ts. *ependen-y U A re ations8ip w8ere t8e se7anti- -8ara-teristi-s of one entity re y upon and -onstrain t8e se7anti- -8ara-teristi-s of anot8er entity. *esi<n pattern U A do-u7ented so ution to a -o77on y en-ountered desi<n prob" e7. In <enera # a desi<n pattern presents a prob e7# fo owed by a des-ription of its so ution in a <i9en -onte;t and pro<ra77in< an<ua<e. *estru-tor U A 7et8od t8at is e;e-uted w8en t8e obDe-t is <arba<e -o e-ted (auto" 7ati-a y or manuall&) *o-u7entation -o77ent U A :a9a -o77ent t8at be<ins wit8 a @ !!A and ends wit8 @! A# and -ontains a des-ription and spe-ia ta<s t8at are parsed by t8e :a9ado- uti " ity to produ-e do-u7entation. *o7ain U An area of e;pertise# &now ed<e# or a-ti9ity. *yna7i- oadin< (of - asses) U 08e oadin< of - asses dyna7i-a y (at run ti7e) w8en t8ey are first referen-ed by an app i-ation. 08e des&top :a9a en9iron7ent# for e;a7p e# pro9ides a - ass oader -apab e of findin< and oadin< a na7ed - ass ap" pearin< in any of a pres-ribed ist of o-ations# w8i-8 7ay be eit8er o-a or re7ote. In rea "ti7e syste7s# dyna7i- - ass oadin< is <enera y not supported or per7itted. En-apsu ation U 08e de<ree to w8i-8 an appropriate 7e-8anis7 is used to 8ide t8e interna data# stru-ture# and i7p e7entation of an obDe-t or ot8er entity. Enu7eration U A type t8at defines a ist of na7ed 9a ues t8at 7a&e up t8e a owab e ran<e for 9a ues of t8at type. Error U *is-repan-y between a -o7puted# obser9ed or 7easured 9a ue or -ondition and t8e true# spe-ified or t8eoreti-a y -orre-t 9a ue or -ondition. ,a-tor U 08e a-t of reor<aniEin< one or 7ore types or - asses by e;tra-tin< respon"
21
sibi ities fro7 e;istin< - asses and synt8esiEin< new - asses to 8and e t8ese respon" sibi ities. ,ie d U An instan-e 9ariab e or data 7e7ber of an obDe-t. ,unda7enta data type U A type t8at typi-a y reHuires on y one i7p e7entation and is -o77on y used to -onstru-t ot8er# 7ore usefu types. *ates# -o7p e; nu7bers# in&ed" ists# and 9e-tors are e;a7p es of -o77on funda7enta data types. 1ard rea "ti7e syste7 U A syste7 t8at <uarantees t8at ti7e"-riti-a a-tions wi a " ways be perfor7ed at t8e spe-ified ti7e. 1ard rea ti7e syste7s re y on ti7in< -on" straints bein< pro9ed usin< t8eoreti-a stati- ana ysis te-8niHues prior to dep oy7ent. I7p e7entation U 08e -on-rete rea iEation of a -ontra-t defined by a type# abstra-t - ass# or interfa-e. 08e a-tua -ode. I7p e7entation - ass U A -on-rete - ass t8at pro9ides an i7p e7entation for a type# abstra-t - ass# or interfa-e. I7p e7entation in8eritan-e U 08e a-tion or 7e-8anis7 by w8i-8 a sub- ass in8erits t8e i7p e7entation and interfa-e fro7 one or 7ore parent - asses. In8eritan-e U A 7e-8anis7 by w8i-8 7ore spe-ifi- e e7ents in-orporate (in8erit) t8e stru-ture and be8a9ior of 7ore <enera e e7ents. In8eritan-e -an be used to support <enera iEation# or 7isused to support on y -ode s8arin<# wit8out atte7ptin< to fo ow be8a9iora subtypin< ru es. Instan-e U 08e -on-rete representation of an obDe-t. Instantiation U 08e a-t of a o-atin< and initia iEin< an obDe-t fro7 a - ass. Interfa-e U A definition of t8e features a--essib e to - ients of a - ass. Interfa-es are distin-t fro7 - asses# w8i-8 7ay a so -ontain 7et8ods# asso-iations and 7odifiab e attributes. %ote: 08e /$2 definition of interfa-e differs s i<8t y fro7 t8at defined by :a9a in t8at :a9a interfa-es 7ay -ontain -onstant fie ds# w8i e /$2 interfa-es 7ay -ontain on y operations. Interfa-e in8eritan-e U 08e in8eritan-e of t8e interfa-e of a 7ore spe-ifi- e e7ent. *oes not in- ude in8eritan-e of t8e i7p e7entation. Interrupt U A suspension of a tas&# su-8 as t8e e;e-ution of a -o7puter pro<ra7# -aused by an e9ent e;terna to t8at tas&# and perfor7ed in su-8 a way t8at t8e tas& -an be resu7ed. In9ariant U An e;pression t8at des-ribes t8e we "defined# e<a states of an obDe-t. Qeyword U A word used to 7ar& an<ua<e -onstru-ts in t8e synta; definition of a pro<ra77in< an<ua<e. 2aEy initia iEation U 08e a-t of de ayin< t8e initia iEation of a data 9a ue unti t8e first use or a--ess of t8e data 9a ue. 2o-a 9ariab e U A 9ariab e w8ose s-ope is restri-ted to a sin< e -o7pound state" 7ent. $et8od U 08e i7p e7entation of an operation. A 7et8od spe-ifies t8e a <orit87 or pro-edure asso-iated wit8 an operation. $onitorin< U ,un-tiona ity wit8in a syste7 w8i-8 is desi<ned to dete-t ano7a ous be8a9ior of t8at syste7. .bDe-t U An entity wit8 a we "defined boundary and identity t8at en-apsu ates state
22
and be8a9ior. State is represented by attributes and re ations8ipsP be8a9ior is repre" sented by operations and 7et8ods# and state 7a-8ines. .peration U A ser9i-e t8at -an be reHuested of an obDe-t. An operation -orresponds to an abstra-t 7et8od de- aration in :a9a. It does not define an asso-iated i7p e" 7entation. .9erridin< U 08e redefinition of an operation or 7et8od in a sub- ass. Pa-&a<e U A 7e-8anis7 for or<aniEin< and na7in< a -o e-tion of re ated - asses. Pa-&a<e a--ess U 08e defau t a--ess -ontro -8ara-teristi- app ied in :a9a to inter" fa-es# - asses# and - ass 7e7bers. Para7eter U A 9ariab e t8at is bound to an ar<u7ent 9a ue passed into a 7et8od. Parent U In an in8eritan-e re ations8ip# t8e <enera iEation of anot8er e e7ent# pro" du-in< t8e -8i d. Pattern U A do-u7ented so ution to a -o77on y en-ountered ana ysis or desi<n prob e7. Ea-8 pattern do-u7ents a sin< e so ution to t8e prob e7 in a <i9en -onte;t. Po y7orp8is7 U 08e -on-ept or 7e-8anis7 by w8i-8 obDe-ts of different types in" 8erit t8e responsibi ity for i7p e7entin< t8e sa7e operation# but respond different y to t8e in9o-ation of t8at operation. Po y7orp8i- U A trait or -8ara-teristi- of an obDe-t w8ereby t8at obDe-t -an appear as se9era different types at t8e sa7e ti7e. Post-ondition U A -onstraint or assertion t8at 7ust 8o d true fo owin< t8e -o7p etion of an operation. Pre-ondition U A -onstraint or assertion t8at 7ust 8o d true at t8e start of an opera" tion. Pri7iti9e type U A basi- an<ua<e type t8at represents a pure 9a ue and 8as no dis" tin-t identity as an obDe-t. 08e pri7iti9es pro9ided by :a9a in- ude boolean# byte# char# double# float# int# long# and short. Pri9ate a--ess U An a--ess -ontro -8ara-teristi- app ied to - ass 7e7bers. C ass 7e7bers de- ared wit8 t8e private a--ess 7odifier are on y a--essib e to -ode in t8e sa7e - ass and are not in8erited by sub- asses. Property U A na7ed -8ara-teristi- or attribute of a type# - ass# or obDe-t. Prote-ted a--ess U An a--ess -ontro -8ara-teristi- app ied to - ass 7e7bers. C ass 7e7bers de- ared wit8 t8e protected a--ess 7odifier are a--essib e to -ode in t8e sa7e - ass and pa-&a<e# and fro7 -ode in sub- asses# and t8ey are in8erited by sub- asses. Pub i- a--ess U An a--ess -ontro -8ara-teristi- app ied to interfa-es# - asses# and - ass 7e7bers. C ass 7e7bers de- ared wit8 t8e public a--ess 7odifier are a-" -essib e anyw8ere t8e - ass is a--essib e and are in8erited by sub- asses. C asses and interfa-es de- ared wit8 t8e public a--ess 7odifier are 9isib e# a--essib e and 8eritab e outside of a pa-&a<e. )e ations8ip U A se7anti- -onne-tion a7on< 7ode e e7ents. E;a7p es of re ation" s8ips in- ude asso-iations and <enera iEations. )esponsibi ity U A purpose or ob i<ation assi<ned to a type. )obustness U 08e e;tent to w8i-8 software -an -ontinue to operate -orre-t y despite of in9a id inputs.
2(
Ser9i-e U .ne or 7ore operations pro9ided by a type# - ass# or obDe-t to a--o7p is8 usefu wor& on be8a f of one or 7ore - ients. Si<nature U 08e na7e# para7eter types# return type# and possib e e;-eptions asso" -iated wit8 an operation. Soft rea "ti7e syste7 U A syste7 in w8i-8 an a-tion perfor7ed at t8e wron< ti7e (ei" t8er too ear y or too ate) is -onsidered a--eptab e but not desirab e. Soft rea "ti7e syste7s re y on e7piri-a (statisti-a ) 7easure7ents and 8euristi- enfor-e7ent of resour-e bud<ets to i7pro9e t8e i&e i8ood of -o7p yin< wit8 ti7in< -onstraints. Software U A set of -o7puter pro<ra7s# pro-edures# do-u7entation and t8eir asso" -iated data. Sour-e -ode U Code written in a sour-e an<ua<es# su-8 as asse7b y an<ua<e and6or 8i<8 e9e an<ua<e# in a 7a-8ine"readab e for7 for input to an asse7b er or a -o7pi er. State U A -ondition or situation durin< t8e ife of an obDe-t durin< w8i-8 it satisfies so7e -ondition# perfor7s so7e a-ti9ity# or waits for so7e e9ent. Stati- ana yEer U A software too t8at 8e ps to re9ea -ertain properties of a pro<ra7 wit8out e;e-utin< t8e pro<ra7. Sub- ass U In a <enera iEation re ations8ip# t8e spe-ia iEation of anot8er - assP t8e so"-a ed super- ass or parent - ass. Sub- ass U A - ass t8at in8erits attributes and 7et8ods fro7 anot8er - ass. Subinterfa-e U 08e spe-ia iEation of anot8er interfa-e. Subtype U 08e 7ore spe-ifi- type in a spe-ia iEation"<enera iEation re ations8ip. Super- ass U In a <enera iEation re ations8ip# t8e <enera iEation of anot8er - assP t8e sub- ass. Syn-8roniEation U 08e pro-ess or 7e-8anis7 used to preser9e t8e in9ariant states of a pro<ra7 or obDe-t in t8e presen-e of 7u tip e t8reads. Syn-8roniEed U A -8ara-teristi- of a :a9a 7et8od or a b o-& of -ode. A syn-8roniEed 7et8od or b o-& a ows on y one t8read at a ti7e to e;e-ute wit8in t8e -riti-a se-tion defined by t8at 7et8od or b o-&. Syste7 U A -o e-tion of 8ardware and software -o7ponents or<aniEed to a--o7" p is8 a spe-ifi- fun-tion or set of fun-tions. 0estin< U 08e pro-ess of e;er-isin< a syste7 or syste7 -o7ponent to 9erify t8at it satisfies spe-ified reHuire7ents and to dete-t errors. 0ra-eabi ity U 08e e9iden-e of an asso-iation between ite7s# su-8 as between pro" -ess outputs# between an output and its ori<inatin< pro-ess# or between a reHuire" 7ent and its i7p e7entation. 08read U A sin< e f ow of -ontro f ow wit8in a pro-ess t8at e;e-utes a seHuen-e of instru-tions in an independent e;e-ution -onte;t. 0ype U *efines t8e -o77on responsibi ities # be8a9ior# and operations asso-iated wit8 a set of si7i ar obDe-ts. A type does not define an i7p e7entation. /n-8e-&ed e;-eption U Any e;-eption t8at is deri9ed fro7 Dava.lang.RunTimeException or Dava.lang.Error. A 7et8od t8at t8rows# or is a re-ipient of# an un-8e-&ed e;-eption is not reHuired to 8and e t8e e;-eption or de- are t8e e;-eption in its throws - ause.
BSSC 2005(2) Issue 1.0 C1AP0E) 1 I%0).*/C0I.% 3ariab e U A typed# na7ed -ontainer for 8o din< obDe-t referen-es or data 9a ues.
24
3isibi ity U 08e de<ree to w8i-8 an entity 7ay be a--essed fro7 outside of a parti-u" ar s-ope.
"./
5cronyms
5!# 5SC## 59T C8R'5 C!( 3CSS 3J' 0C 0(# :RT :S :T;L #D3 #/8 J5R JC3 JC! JD'C JD< J%33 J-# J%;3 J%S3 JSS3 J=; 88 8R' !C! !8S#> R;# R/T App i-ation Pro<ra77in< Interfa-e A7eri-an Standard Code for Infor7ation Inter-8an<e Abstra-t Findow 0oo &it Co77on .bDe-t )eHuest Bro&er Ar-8ite-ture Centra Pro-essin< /nit European Cooperation for Spa-e Standardisation Enterprise :a9aBeans 5arba<e Co e-tion 5rap8i-a /ser Interfa-e 1ard )ea "0i7e 1ot Spot (-o7pi in<) 1yperte;t $ar&"up 2an<ua<e Inte<rated *e9e op7ent En9iron7ent Input6.utput :a9a Ar-8i9e :a9a Crypto<rap8y E;tension :a9a Co77unity Pro-ess :a9a *ata Base Conne-ti9ity :a9a *e9e op7ent Qit :a9a Enterprise Edition :a9a %ati9e Interfa-e :a9a 2 $i-ro Edition :a9a Standard Edition :a9a Se-ure So-&ets E;tension :a9a 3irtua $a-8ine .bDe-t"oriented .bDe-t )eHuest Bro&er Priority Cei in< Proto-o Portab e .peratin< Syste7 Interfa-e " /%I+ )e7ote $et8od In9o-ation )ea 0i7e
BSSC 2005(2) Issue 1.0 C1AP0E) 1 I%0).*/C0I.% RT8S RTSJ SSL S9T (;L )ea 0i7e .peratin< Syste7 )ea 0i7e Spe-ifi-ation for :a9a Se-ure So-&ets 2ayer Standard Fid<et 2ibrary /nified $ode in< 2an<ua<e
25
BSSC 2005(2) Issue 1.0 C1AP0E) 2 I%S0A22A0I.%# B/I2* A%* /P*A0ES
2>
Chapter % #nstallation& 'uild and (pdates

%." #ntroduction
It is i7portant for e9ery software de9e op7ent proDe-t to pro9ide -o77on and unifor7 bui d and update pro-edures# and to a ow for -on9enient and re iab e de" p oy7ent and insta ation of its produ-ts. 08e :a9a p atfor7 offers a nu7ber of fa-i i" ties t8at dire-t y address t8ese essentia proDe-t needs. 08is -8apter is -on-erned wit8 8ow to 7a&e better use of t8e7.
%.%
5pache 5nt
8pache 8nt RA%0S (or si7p y 8nt) is a :a9a based bui d too intended to auto" 7ate t8e -o7pi ation of software syste7s# as we as 7any ot8er re ated tas&s. 8nt based -o7pi ation syste7s are <uaranteed to run on any :a9a -o7p iant p atfor7. )u e 1: /se t8e 8pache 8nt too to auto7ati-a y bui d your proDe-t. Rationale 8nt a ows to -reate portab e -o7pi ation syste7s# t8us 7a&in< it possib e for t8e de9e op7ent a-ti9ities of a proDe-t to ta&e p a-e in 8etero<eneous software and 8ardware p atfor7s. +ecommen!ation 1 7se the 8nt tool to automate as man& a!!itional pro:ect tas;s as possi1le$ Rationale Apart fro7 supportin< t8e -o7pi ation pro-ess# 8nt 7a&es it possib e to auto" 7ate a 9ariety of software Hua ity assuran-e# insta ation# distribution# and 7ainte" nan-e re ated tas&s# i&e runnin< auto7ated test suites# -reatin< pa-&a<ed fi es for distribution# and <eneratin< do-u7entation# a7on< 7any ot8ers. /se 8nt to auto7ate as 7any su-8 tas&s as possib e.
%.*
!references
+ecommen!ation % 7se the <a)a Preferences 8PI to store an! retrie)e all runtime configuration !ata$ )un"ti7e -onfi<uration data is a data ne-essary to adapt a software app i-a" tion to t8e needs of different users and en9iron7ents. /se t8e <a)a Preferences 8PI RS/%PrefS to store a -onfi<uration re ated data.
BSSC 2005(2) Issue 1.0 C1AP0E) 2 I%S0A22A0I.%# B/I2* A%* /P*A0ES Rationale
2'
08e Preferen-es API 7ana<es -onfi<uration data in a si7p e# -o7p ete y p at" for7 independent way. In parti-u ar# it offers a nu7ber of ad9anta<es wit8 respe-t to usin< property fi es# w8i-8 is t8e traditiona approa-8 to 8and e t8is prob e7.
%.,
Soft6are Distribution
)u e 2: F8en distributin< a proDe-t# pa-&a<e a ne-essary - ass and resour-e fi es in a :ar fi e. <ar fi es are a standard way to distribute :a9a pro<ra7s. In order to distribute a pro<ra7# pa-&a<e a re e9ant - ass and resour-e fi es (i-ons# interna read"on y data fi es) in a :ar fi e. Rationale A nu7ber of prob e7s -an arise w8en -opyin< a pro<ra7Ms run"ti7e fi es to a different 8ardware or software p atfor7. Su-8 prob e7s -an be a ready 9isib e w8en atte7ptin< to -opy t8e fi es# or 7ay on y be-o7e e9ident w8en runnin< t8e software ater on:
File name length ,i e na7e en<t8 restri-tions in so7e syste7s 7ay -ause fi e na7es to be in-orre-t y -opied# or 7ay <enerate na7in< -onf i-ts be-ause of na7e trun-ation. 7pper- an! lower-case !istinctions 08e way a syste7 7ana<es upper" and ower"-ase in fi e na7es -ou d -ause -onf i-ts w8en fi es are transferred. Special file names So7e p atfor7s assi<n spe-ia 7eanin< to -ertain fi e na7es# su-8 as @"#TA or @conA. Special characters Ea-8 p atfor7 i7its t8e set of -8ara-ters a--epted in fi e na7es to a different set.
/sin< a :ar fi e a9oids a of t8ese prob e7s# be-ause :ar fi es 8a9e an interna fi e na7in< syste7 t8at is -o7p ete y independent fro7 t8at of t8e under yin< operat" in< syste7.
%./
#mplementation ?iles
)u e (: *efine on y one - ass or interfa-e per .java fi e. Rationale *oin< so si7p ifies 7aintenan-e.
BSSC 2005(2) Issue 1.0 C1AP0E) ( S./)CE C.*E S0)/C0/)E
2!
Chapter * Source Code Structure

/nifor7 sour-e -ode stru-ture and for7attin< are funda7enta for an adeHuate -o aboration between pro<ra77ers. 08e ru es and re-o77endations in t8is -8apter define a -onsistent -ode for7attin< sty e to be app ied in a ESA re ated software de" 9e op7ent proDe-ts. Code for7attin< issues are often -ontentious# probab y be-ause t8ey are 7ain y a 7atter of taste. A t8ou<8 t8is do-u7ent -annot fit e9eryoneMs persona prefer" en-es# it spe-ifies a reasonab e for7attin< sty e# intended to be <enera y readab e and re ati9e y si7p e to fo ow w8i e writin< -ode. Additiona y# sin-e 7ost of t8e ru es and re-o77endations in t8is -8apter are based on e;istin<# wide y &nown standards ( i&e t8ose fro7 Sun $i-rosyste7s RS/%CodeS) 7any 7e7bers of t8e :a9a de9e op" 7ent -o77unity are i&e y to a ready be fa7i iar wit8 t8e7. 08e se-tions in t8is -8apter address a 9ariety of -ode e e7ents# startin< wit8 t8e bi<<er and 7ore <enera ones# and <oin< down to t8e s7a er# 7ore detai ed ones.
*."
#mplementation ?iles
)u e 4: /se t8e fo owin< stru-ture for a i7p e7entation fi es:
Start wit8 t8e be<innin< -o77ents. ,o ow wit8 pa-&a<e and i7port state7ents. Put - ass and interfa-e definitions at t8e end of t8e fi e.
Rationale ,or7attin< -on9entions are ne-essary to a-8ie9e -ode unifor7ity. +ecommen!ation 3 7se a stan!ar! template or utilit& program to pro)i!e a starting point for implementation files$ Rationale Introdu-in< t8e e e7ents spe-ified by t8is standard or by any additiona proDe-t spe-ifi- standards in e9ery i7p e7entation fi e -an be a burden for t8e pro<ra77er. Copyin< t8ese e e7ents fro7 a standard# proDe-t"wide te7p ate fi e usua y si7p ifies t8e tas& of -reatin< new fi es and 7a&es it 7ore -onsistent. An additiona possibi ity is to pro9ide a uti ity pro<ra7 or s-ript# w8i-8 -an <ener" ate an initia i7p e7entation fi e# based on proDe-t"wide infor7ation and possib y in" for7ation pro9ided by t8e pro<ra77er or obtained fro7 t8e pro<ra77in< en9iron"
2=
7ent. Su-8 a pro<ra7 -ou d sa9e t8e pro<ra77er a nu7ber of additiona -us" to7iEation steps t8at wou d be needed w8en usin< a si7p e te7p ate fi e. )u e 5: *o not use tab -8ara-ters in i7p e7entation fi es# use p ain spa-es instead. Rationale Interpretation of tab -8ara-ters 9aries a-ross operatin< syste7s and pro<ra7" 7in< en9iron7ents. Code t8at appears to be -orre-t y for7atted w8en disp ayed in t8e ori<ina editin< en9iron7ent -an be 9irtua y i7possib e to read w8en 7o9ed to an en9iron7ent t8at interprets tab -8ara-ters in a different way. 0o a9oid t8is prob e7# use spa-es instead of tabs to indent and a i<n sour-e -ode. $ost 7odern pro<ra77in< en9iron7ents offer options to do t8is auto7ati-a y. .t8erwise it -an be done 7anua y. )u e >: /se t8e fo owin< order to de- are 7e7bers of a - ass:
C ass 9ariab es (de- ared static). Instan-e 9ariab es. Constru-tors (at east one). finali$e 7et8od (destru-tor) if ne-essary. C ass 7et8ods (de- ared static). $et8ods:
set6get .t8er 7et8ods
Additiona y# inside ea-8 one of t8ese <roups# de- are 7e7bers wit8 a 8i<8er 9isibi ity first. 08at is# start wit8 public 7e7bers# -ontinue wit8 pa-&a<e 9isib e 7e7bers (not Hua ified)# 7o9e to protected 7e7bers# and end wit8 private 7e7bers. Rationale ,or7attin< -on9entions are ne-essary to a-8ie9e -ode unifor7ity.
*.%
0eneral Code #ndentation Rules

08is se-tion -ontains so7e ru es and re-o77endations t8at app y to a -ode e e7ents. 08ey are intended to be -onsistent wit8 Sun $i-rosyste7sMs :a9a Codin< Con9entions RS/%CodeS. )u e ': /se four spa-es of indentation. F8en indentin< t8e -ode inside de- aration and -ontro stru-tures# a ways use four additiona spa-es wit8 respe-t to t8e pre9ious e9e . $ore spe-ifi- ru es and re-" o77endations in t8is do-u7ent are a ways -onsistent wit8 t8is <enera -on9ention.
BSSC 2005(2) Issue 1.0 C1AP0E) ( S./)CE C.*E S0)/C0/)E Rationale ,or7attin< -on9entions are ne-essary to a-8ie9e -ode unifor7ity. +ecommen!ation 4 8)oi! lines longer than 00 characters$ Rationale
(0
S8orter ines are easier to read. Additiona y# uti ity pro<ra7s dea in< wit8 sour-e -ode# i&e te;t editors and -ode pretty printers# 7ay 8a9e troub e dea in< wit8 e;-essi9e y on< ines. +ecommen!ation # =hen 1rea;ing long lines, follow these gui!elines
Brea& after -o77as. Brea& before operators. Prefer brea&in< between ar<e 8i<8" e9e sube;pressions to brea&in< between s7a er ower" e9e sube;pressions. A i<n t8e te;t in a new ine# wit8 t8e be<innin< of t8e e;pression at t8e sa7e synta-ti-a e9e on t8e pre9ious ine. If t8e abo9e <uide ines ead to -onfusin< or -u7berso7e for7attin<# indent t8e se-ond ine ! spa-es instead.
Rationale 08ese <uide ines -orrespond to -o77on y used typo<rap8i-a -on9entions# w8i-8 are <enera y a--epted to i7pro9e readabi ity. 3 ample
Brea& after -o77as. Prefer

system.out.printline%final&time' (((((((((((((((((((((%final&time()(initial&time*(!(+*,
to
system.out.printline%final&time'(%final&time() (((((((((((((((((((((initial&time*(!(+*,
Brea& before operators. Prefer

final&price(-(basic&price(!(tax&rate ((((((((((((((.(initial&price,
(brea& before @.A) to

final&price(-(basic&price(!(tax&rate(. ((((((((((((((initial&price,
(brea& after @.A.)
Prefer brea&in< between ar<e 8i<8" e9e sube;pressions to brea&in< between s7a er ower" e9e sube;pressions:
pos(-(pos/(.(speed(!(time(. ((((((%acceleration(!(time(!(time*( (0,
BSSC 2005(2) Issue 1.0 C1AP0E) ( S./)CE C.*E S0)/C0/)E s8ou d be preferred to
pos(-(pos/(.(speed(!(time(.(%acceleration(!(time (((((((((((((((((((((((((((((!(time*( (0,
(1
A i<n t8e te;t in a new ine# wit8 t8e be<innin< of t8e e;pression at t8e sa7e synta-ti-a e9e on t8e pre9ious ine. Prefer
self.get1lient"ist%*.retrieve%base1lient()(process1ount ((((((((((((((((((((((((((((((.(offset*,
to
self.get1lient"ist%*.retrieve%base1lient()(process1ount (((((((((((((((((((((((((((((((((((((((((.(offset*,
If t8e abo9e <uide ines ead to -onfusin< or -u7berso7e for7attin<# indent t8e se-ond ine ! spa-es instead. Prefer:
members.get2ember3y4ame%member4ame*.store% ((((((((self.database'(self.get#riority%*(.(priority5ncrease*,
to
members.get2ember3y4ame%member4ame*.store%self.database' ((((((((((((((((((((((((((((((((((((((((((self.get#riority%*(. ((((((((((((((((((((((((((((((((((((((((((priority5ncrease*,
*.*
Definitions
)u e !: ,or7at - ass and interfa-e definitions a--ordin< to t8e fo owin< 7ode :
class(Sample(extends(Object( { ((((int(ivar6, ((((int(ivar0, ((((Sample%int(i'(int(j*( (((({ ((((((((ivar6(-(i, ((((((((ivar0(-(j, ((((}( (end(method ((((int(empty2ethod%*({} ((((... }( (end(class
So7e re7ar&s about t8e pre9ious 7ode :
2ea9e no spa-e between a 7et8od na7e and t8e fo owin< parent8esis @%@. 08e open bra-e @{@ is put on its own ine (Dust be ow t8e de- aration state7ent) and is a i<ned wit8 t8e end bra-e R5%/:A3AS %ote t8is differs fro7 t8e S/% <uide ine RS/%CodeS. 08e - osin< bra-e @}A starts a ine by itse f indented to 7at-8 its -orrespondin< openin< state7ent# e;-ept w8en it is a nu state7ent in w8i-8 -ase# t8e @OA s8ou d appear i77ediate y after t8e @{@. $et8ods are separated by a b an& ine.
BSSC 2005(2) Issue 1.0 C1AP0E) ( S./)CE C.*E S0)/C0/)E Rationale ,or7attin< -on9entions are ne-essary to a-8ie9e -ode unifor7ity.
(2
,o owin< t8e 5%/ -on9ention for bra-in< sty e 7a&es it 7ore easier and Hui-&" er to re-o<niEe -ode stru-ture. 08is is parti-u ar y true in t8e -ase of deep nestin<. Consisten-y in bra-e p a-e7ent re7ains e9en in t8e fa-e of ine brea&s in on< de-" arations. 08is is parti-u ar y <ood for -ode inspe-tion. )u e =: Put sin< e 9ariab e definitions in separate ines. Rationale *efinin< 7any 9ariab es in a sin< e ine# 7a&es it 7ore diffi-u t to -8an<e t8e type of one of t8e de- arations wit8out -8an<in< t8e re7ainin< ones. 08is -ou d ead to inad9ertent y introdu-in< pro<ra77in< errors. 3 ample Instead of writin<
int(counter'(total,( (7rong8
write
int(counter, int(total,
*.,
Statements
)u e 10: Put sin< e state7ents in separate ines. Rationale $any state7ents in a sin< e ine are 8arder to read. 3 ample Instead of writin<
counter(-(initial,(counter..,( (7rong8
write
counter(-(initial, counter..,
)u e 11: ,or7at -o7pound state7ents a--ordin< to t8e fo owin< <uide ines:
Put t8e openin< bra-e @{@ at t8e end of t8e openin< ine for t8e -o7pound state" 7ent. Indent en- osed state7ents one e9e (four spa-es) wit8 respe-t to t8e -o7" pound state7ents. Put t8e - osin< bra-e @}A in a ine of its own# wit8 t8e sa7e e9e of indentation of t8e openin< ine.
BSSC 2005(2) Issue 1.0 C1AP0E) ( S./)CE C.*E S0)/C0/)E Rationale ,or7attin< -on9entions are ne-essary to a-8ie9e -ode unifor7ity. )u e 12: A ways put bra-es around state7ents -ontained in -ontro stru-tures.
((
State7ents 8an<in< fro7 -ontro stru-tures i&e if# while# for# and ot8ers s8a a ways 8a9e bra-es surroundin< t8e7# e9en if t8e b o-& -ontains a sin< e state" 7ent. F8i e t8e an<ua<e enab es you to use si7p e# non"b o-& state7ents as t8e body of t8ese -onstru-ts# a ways use a b o-& state7ent in su-8 situations. Rationale B o-& state7ents redu-e t8e a7bi<uity t8at often arises w8en -ontro -onstru-ts are nested# and pro9ide a 7e-8anis7 for or<aniEin< t8e -ode for i7pro9ed readabi i" ty. 08is pra-ti-e 8e ps to a9oid pro<ra77in< errors resu tin< fro7 interpretin< t8e pro<ra7 as t8e indentation su<<ests# and not as t8e -o7pi er parses it. ,or e;a7" p e# a pro<ra77er wantin< to 7odify t8e in-orre-t e;a7p e abo9e -ou d -8an<e it into
if(%position(9(si$e* ((((position.., ((((remaining::,
to 7ean t8at bot8 (in-re7ent and de-re7ent) state7ents s8ou d be e;e-uted w8en t8e -ondition is true. Sin-e t8e indentation is -onsistent wit8 8is intent# it -ou d be dif" fi-u t for 8i7 to spot t8e a-& of t8e bra-es. 08is prob e7 wou d not 8a9e arisen# 8ad t8e pro<ra7 been written as in t8e -orre-t e;a7p e abo9e. 3 ample Instead of writin<
if(%position(9(si$e*( ((((position.., (7rong'(add(braces8
write
if(%position(9(si$e*( { ((((position.., }( (end(if
)u e 1(: ,or7at if:else state7ents a--ordin< to t8e fo owin< 7ode s: Si7p e bran-8 if state7ent:
if(%condition*( { ((((statements, }( (end(if
if state7ent wit8 else:

if(%condition*( { ((((statements,

}( (end(if else( { ((((statements, }( (end(else
(4
$u ti"bran-8 if state7ent:
if(%condition*( { ((((statements, }( (end(if else(if(%condition*( { ((((statements, }( (end(if else( { ((((statements, }( (end(else
08e indentation of if state7ents wit8 an else - ause and of 7u ti"bran-8 if state7ents differs s i<8t y fro7 t8at re-o77ended by t8e S/% standard RS/%CodeS. Puttin< else - auses in a separate ine in-reases t8e readabi ity of t8e w8o e stru-" ture. Rationale ,or7attin< -on9entions are ne-essary to a-8ie9e -ode unifor7ity. )u e 14: ,or7at for state7ents a--ordin< to t8e fo owin< 7ode :
for(%initialization,(condition,(update*( { ((((statements, }( (end(for
for state7ents wit8out a body s8ou d be for7atted as fo ows:

for(%initialization,(condition,(update*,
(note t8e se7i-o on @,A at t8e end.) Rationale ,or7attin< -on9entions are ne-essary to a-8ie9e -ode unifor7ity. )u e 15: ,or7at while state7ents a--ordin< to t8e fo owin< 7ode :
while(%condition*( { ((((statements, }( (end(while
Rationale ,or7attin< -on9entions are ne-essary to a-8ie9e -ode unifor7ity.
BSSC 2005(2) Issue 1.0 C1AP0E) ( S./)CE C.*E S0)/C0/)E )u e 1>: ,or7at do:while state7ents a--ordin< to t8e fo owin< 7ode :
do( { ((((statements, }(while(%condition*,
(5
Rationale ,or7attin< -on9entions are ne-essary to a-8ie9e -ode unifor7ity. )u e 1': ,or7at switch state7ents a--ordin< to t8e fo owin< 7ode :
switch(%condition*( { case(CASE1; ((((statements, (((( !(falls(through(! case(CASE2; ((((statements, ((((brea<, case(CASE3; ((((statements, ((((brea<, default; ((((statements, ((((brea<, }( (end(switch
Cases wit8out a brea< state7ent s8ou d in- ude a !(falls(through(! -o77entary to indi-ate e;p i-it y t8at t8ey fall through to t8e ne;t -ase. A switch state7ents s8ou d in- ude a default -ase. 08e ast -ase in t8e switch state7ent s8ou d a so end wit8 a brea< state" 7ent.
Rationale ,or7attin< -on9entions are ne-essary to a-8ie9e -ode unifor7ity. )u e 1!: ,or7at try:catch state7ents a--ordin< to t8e fo owin< 7ode : Si7p e try state7ent:
try( { ((((statements, }( (end(try catch(%ExceptionClass(e*( { ((((statements, }( (end(catch
try state7ent wit8 finally - ause:

try(

{ ((((statements, }( (end(try catch(%Exception1lass(e*( { ((((statements, }( (end(catch finally( { ((((statements, }( (end(method
(>
Rationale ,or7attin< -on9entions are ne-essary to a-8ie9e -ode unifor7ity. +ecommen!ation 2 8)oi! parentheses aroun! the return )alues of return statements$ 3 ample Instead of writin<
return%total*,
or
return(%total*,
si7p y write
return(total,
*./
'lan@ Lines and Spaces

)u e 1=: 2ea9e two b an& ines:
Between se-tions of a sour-e fi e. Between - ass and interfa-e definitions.
Rationale B an& ines in t8e spe-ified p a-es 8e p identify t8e <enera stru-ture of an i7" p e7entation fi e. )u e 20: 2ea9e one b an& ine:
Between 7et8ods. Between t8e o-a 9ariab e definitions in a 7et8od or -o7pound state7ent and its first state7ent.
BSSC 2005(2) Issue 1.0 C1AP0E) ( S./)CE C.*E S0)/C0/)E Rationale
('
B an& ines in t8e spe-ified p a-es 8e p identify t8e stru-ture of - ass and 7et8od definitions. +ecommen!ation > Separate groups of statements in a metho! using single 1lan; lines$ State7ents in a 7et8od -an usua y be bro&en into <roups t8at perfor7 -on-ep" tua y separate tas&s (i.e. basi- steps in an a <orit87). It is a <ood idea to separate su-8 <roups wit8 sin< e b an& ines to 7a&e t8e7 7ore ob9ious. Rationale 08is pra-ti-e 8e ps to better -o77uni-ate t8e intent of t8e pro<ra7. 3 ample
void(print=ttrib"ist%=ttributes(atts*( { ((((int(length(-(atts.get"ength%*, ((((int(i, ((((for(%i(-(/,(i(9(length,(i..*( (((({ ((((((((if(%S=>?elpers.is>2"=ttrib%atts'(i'(@space@**( (({ (((((((((((( (Omit(xml;space(declarations(in(?T2". ((((((((((((brea<, ((((((((}( (end(if (((((((( (Aind(a(suitable(attribute(name. ((((((((String(name(-(atts.getB4ame%i*, ((((((((if(%name(--(null(CC(name.eDuals%@@**( (((((((({ ((((((((((((name(-(atts.get"ocal4ame%i*, ((((((((}( (end(if ((((((((ti.print2ar<up%@(@(.(name(.(@-E@@*, (((((((( (#rint(the(attribute(value'(but(donFt(compress(spaces. ((((((((ti.escapeText%atts.getGalue%i**, ((((((((ti.print2ar<up%@E@@*, ((((}( (end(for }( (end(method
)u e 21: A ways use a spa-e -8ara-ter:
After -o77as in ar<u7ent ists. Before and after a binary operators# e;-ept for t8e @.A operator. After t8e se7i-o ons (@,A) separatin< t8e e;pressions in a for state7ent. After -asts in e;pressions.
BSSC 2005(2) Issue 1.0 C1AP0E) ( S./)CE C.*E S0)/C0/)E Rationale Spa-e -8ara-ters in t8e spe-ified p a-es 8e p readabi ity:
(!
08ey are o-ated at t8e end or around -ertain synta-ti-a -onstru-ts# and t8us 8e p to identify t8e7 9isua y. 08ey are -onsistent wit8 -o77on typo<rap8i-a -on9entions t8at are we &nown to i7pro9e readabi ity.
BSSC 2005(2) Issue 1.0 C1AP0E) 4 %A$I%5
(=
Chapter , -aming
,." #ntroduction
ProDe-ts often under<o periods of fast de9e op7ent# w8ere de9e opers -on-en" trate on i7p e7entin< fun-tiona ity# and ea9e ot8er i7portant# but not so ur<ent tas&s i&e do-u7entation for a ater ti7e. A &ey i7p i-ation of t8is fa-t is t8at often# t8e on y part of an o9era software produ-t t8at is up to date is its sour-e -ode. ,or t8is reason# - ear and se f"do-u7entin< -ode is a ways 9ery 9a uab e. C8oosin< de" s-ripti9e pro<ra7 identifiers is one i7portant step to a-8ie9e su-8 -ode. 08is -8apter is -on-erned wit8 issues of na7in< wit8in :a9a sour-e -ode. 08e :a9a pro<ra77in< an<ua<e a ows on< and 7eanin<fu na7es# -onsistent wit8 w8at 7odern software en<ineerin< pra-ti-es en-oura<e. Sin-e na7es are used in a 9ariety of -onte;ts and s-opes# t8is -8apter -o9ers t8e 9arious na7in< situations startin< wit8 t8e 7ore <enera and wider ones and <oin< down to 7ore spe-ifi- and o-a ones.
,.%
0eneral -aming Conventions

08e ru es and re-o77endations in t8is se-tion app y to a types of identifiers possib e in a :a9a pro<ra7. )u e 22: /se A7eri-an En< is8 for identifiers. Identifiers s8a -orrespond to En< is8 words or senten-es# usin< t8e A7eri-an spe in< (i.e. @1olorA# @initiali$eA# @Seriali$ableA# instead of @1olourA# @initialiseA or @SerialisableA.) Rationale $i;ed A7eri-an and Britis8 spe in< -an resu t in identifiers bein< 7istyped. Ad" ditiona y# t8e :a9a standard ibrary uses A7eri-an spe in< for its identifiers. )u e 2(: )estri-t identifiers to t8e ASCII -8ara-ter set. Rationale ,i es -ontainin< non"ASCII identifiers 7ay not disp ay proper y in so7e p at" for7s and 7ay be 8ard to edit proper y. +ecommen!ation 0 Pic; i!entifiers that accuratel& !escri1e the correspon!ing program entit&$ F8i e -odin<# spend so7e ti7e oo&in< for identifiers t8at a--urate y and -on"
40
-ise y des-ribe t8e pro<ra7 entity (- ass# pa-&a<e# instan-e# o-a 9ariab e# et-.) in Huestion. %a7es s8ou d be s8ort# yet 7eanin<fu . 08e -8oi-e of a na7e s8ou d be 7ne7oni-# i.e.# desi<ned to indi-ate to t8e -asua obser9er t8e intent of its use. .ne" -8ara-ter 9ariab e na7es s8ou d be a9oided# e;-ept for te7porary @t8rowawayT 9ari" ab es. Co77on na7es for te7porary 9ariab es are i# j# <# m# and n for inte<ersP c# d# and e for -8ara-ters. Rationale %a7in< -on9entions are ne-essary to a-8ie9e -ode unifor7ity. +ecommen!ation ? 7se terminolog& applica1le to the !omain$ F8i e -8oosin< identifiers# re y as 7u-8 as possib e on a--epted# do7ain spe" -ifi- ter7ino o<y. Rationale *oin< so -an fa-i itate -o77uni-ation between pro<ra77ers and ot8er profes" siona s in9o 9ed in a proDe-t. It a so 8e ps to produ-e 7ore -on-ise and a--urate identifiers. +ecommen!ation 10 8)oi! long .e$g$ more than %0 characters( i!entifiers$ F8i e tryin< to &eep na7es des-ripti9e# a9oid usin< 9ery on< identifiers. Rationale E;tre7e y on< identifiers 7ay be 8ard to re7e7ber# are diffi-u t to type# and 7ay 7a&e -ode 8arder to for7at proper y. +ecommen!ation 11 7se a11re)iations sparingl& an! consistentl&$ A t8ou<8 abbre9iatin< words in identifiers s8ou d be <enera y a9oided# it is so7eti7es ne-essary to do it in order to pre9ent identifiers fro7 be-o7in< e;-es" si9e y on<. In su-8 a -ase# ensure t8at t8e sa7e abbre9iation is a ways used for t8e sa7e ter7. Rationale %a7in< -on9entions are ne-essary to a-8ie9e -ode unifor7ity. )u e 24: A9oid na7es t8at differ on y in -ase. %e9er use in t8e sa7e na7espa-e identifiers t8at 8a9e t8e sa7e etters# but t8at are -apita iEed in different ways. As an additiona re-o77endation# <enera y a9oid puttin< si7i ar identifiers in t8e sa7e na7espa-e. Rationale Si7i ar na7es in a sin< e na7espa-e easi y ead to -odin< errors.
BSSC 2005(2) Issue 1.0 C1AP0E) 4 %A$I%5 )u e 25: Capita iEe t8e first etter of standard a-rony7s.
41
F8en usin< standard a-rony7s in identifiers# -apita iEe on y t8e first etter# not t8e w8o e a-rony7# e9en if su-8 a-rony7 is usua y written in fu upper"-ase. 3 ample /se >mlAile# auxiliaryRmiServer and mainOdbc1onnection instead of >2"Aile# auxiliaryR25Server or mainOH311onnection. Rationale *oin< t8is a ows for - earer separation of words wit8in t8e na7e# 7a&in< identi" fiers easier to read. F8en on y t8e first etter is -apita iEed# words are 7ore easi y distin<uis8ed wit8out any one word bein< do7inant. )u e 2>: *o not 8ide de- arations. *o not de- are na7es in one s-ope t8at 8ide na7es de- ared in a wider s-ope. Pi-& different na7es as ne-essary. Rationale Errors resu tin< fro7 8idin< a de- aration# but sti tryin< to dire-t y refer to t8e de- ared e e7ent# 7ay be 9ery diffi-u t to spot.
,.*
!ac@age -ames
)u e 2': /se t8e re9ersed# ower"-ase for7 of your or<aniEationGs Internet do7ain na7e as t8e root Hua ifier for your pa-&a<e na7es. F8ene9er possib e# any pa-&a<e na7e s8ou d in- ude t8e ower"-ase do7ain na7e of t8e ori<inatin< or<aniEation# in re9erse order. In t8e -ase of ESA# 8owe9er# na7es be<innin< wit8 t8e -o7ponents @int.esaA are not possib e# sin-e @intA is a reser9ed word in t8e :a9a pro<ra77in< an<ua<e and wi be reDe-ted by -o7pi ers and ot8er too s -o7p iant wit8 t8e an<ua<e defini" tion. 08e re-o77ended pa-&a<e na7in< s-8e7a for pa-&a<es de9e oped by ESA proDe-ts is esa.projectname.applicationname.componentname Additiona y# t8e @javaA and @javaxA pa-&a<e na7e -o7ponents 7ust not be used be-ause t8ey are reser9ed for t8e standard ibraries and for e;tension pa-&" a<es pro9ided dire-t y by Sun $i-rosyste7s. Rationale %a7in< -on9entions are ne-essary to a-8ie9e -ode unifor7ity. 3 ample
esa.galileo.ipf.ifcalculator esa.herschel.mps.scheduler
BSSC 2005(2) Issue 1.0 C1AP0E) 4 %A$I%5 )u e 2!: /se a sin< e# ower"-ase word as t8e root na7e of ea-8 pa-&a<e.
42
08e Hua ified portion of a pa-&a<e na7e s8ou d -onsist of a sin< e# ower"-ase word t8at - ear y -aptures t8e purpose and uti ity of t8e pa-&a<e. A pa-&a<e na7e 7ay -onsist of a 7eanin<fu abbre9iation. Rationale %a7in< -on9entions are ne-essary to a-8ie9e -ode unifor7ity.
,.,
Type& Class and #nterface -ames

)u e 2=: Capita iEe t8e first etter of ea-8 word t8at appears in a - ass or interfa-e na7e. Rationale 08e -apita iEation pro9ides a 9isua -ue for separatin< t8e indi9idua words wit8" in ea-8 na7e. 08e eadin< -apita etter a ows for differentiatin< between - ass or in" terfa-e na7es and 9ariab e na7es. 3 ample
public(class(#rintStream(extends(AilterOutputStream( { ... }( (end(class public(interface(=ction"istener(extends(Event"istener( { ... }( (end(interface
)u e (0: /se nouns or adDe-ti9es w8en na7in< interfa-es. /se nouns to na7e interfa-es t8at a-t as ser9i-e de- arations. /se adDe-ti9es to na7e interfa-es t8at a-t as des-riptions of -apabi ities. 08e atter are freHuent y na7ed wit8 adDe-ti9es for7ed by ta-&in< an @ab eA or @ib eA suffi; onto t8e end of a 9erb. Rationale An interfa-e -onstitutes a de- aration of t8e ser9i-es pro9ided by an obDe-t in w8i-8 -ase a noun is an appropriate na7e# or it -onstitutes a des-ription of t8e -apa" bi ities of an obDe-t# in w8i-8 -ase an adDe-ti9e is an appropriate na7e. 3 ample An interfa-e de- arin< a ser9i-e:
public(interface(=ction"istener( { ((((public(void(action#erformed%=ctionEvent(e*, }( (end(interface
Interfa-es de- arin< obDe-t -apabi ities:

public(interface(Runnable { ((((public(void(run%*, }( (end(interface public(interface(=ccessible { ((((public(1ontext(get1ontext%*, }( (end(interface
4(
)u e (1: /se nouns w8en na7in< - asses. Rationale C asses represent -ate<ories of obDe-ts of t8e rea wor d. Su-8 obDe-ts are nor" 7a y referred to usin< nouns. 3 ample So7e e;a7p es fro7 t8e :a9a standard - ass ibrary:
Soc<etAactory IerberosTic<et 2edia4ame 2odifier String1ontent Time
)u e (2: P ura iEe t8e na7es of - asses t8at <roup re ated attributes# stati- ser9i-es or -onstants. 5i9e - asses w8ose instan-es <roup re ated attributes# stati- ser9i-es# or -on" stants a na7e t8at -orresponds to t8e p ura for7 of t8e attribute# ser9i-e# or -on" stant type defined by t8e - ass. Rationale 08e p ura for7 7a&es it - ear t8at t8e instan-es of t8e - ass are -o e-tions. 3 ample So7e e;a7p es fro7 t8e :a9a standard - ass ibrary:
3asic=ttributes "ifespan#olicyOperations #ageRanges Rendering?ints
44
,./
;ethod -ames
)u e ((: /se ower"-ase for t8e first word and -apita iEe on y t8e first etter of ea-8 subseHuent word t8at appears in a 7et8od na7e. Rationale 08e -apita iEation pro9ides a 9isua -ue for separatin< t8e indi9idua words wit8" in ea-8 na7e. 08e eadin< ower"-ase etter a ows for differentiatin< between a 7et8od and a -onstru-tor in9o-ation. 3 ample
insertElement computeTime save extractHata
)u e (4: /se 9erbs in i7perati9e for7 to na7e 7et8ods t8at:
$odify t8e -orrespondin< obDe-t (7odifier 7et8ods). 1a9e border effe-ts (i.e.# disp ayin< infor7ation# writin< to or readin< fro7 a stora<e de9i-e# -8an<in< t8e state of a perip8era # et-.)
Rationale $odifiers and 7et8ods wit8 border effe-ts perfor7 a-tions# w8i-8 are better de" s-ribed by 9erbs. 3 ample $odifier 7et8ods:
insert projectOrthogonal deleteRepeated
$et8ods wit8 border effe-ts:

save draw"ine send2essage
)u e (5: /se 9erbs in present t8ird person to na7e ana yEer 7et8ods returnin< a boo ean 9a ue. Parti-u ar y# for - asses i7p e7entin< :a9aBeans usin< t8e 9erb @isA 7ay be ne-essary. Rationale $et8ods returnin< a boo ean 9a ue test so7e -8ara-teristi- of t8e -orrespond" in< obDe-t.
BSSC 2005(2) Issue 1.0 C1AP0E) 4 %A$I%5 3 ample

isGalid has1hild can#rint
45
)u e (>: /se nouns to na7e ana yEer 7et8ods returnin< a non"boo ean 9a ue# or# a ternati9e y# na7e t8e7 usin< t8e 9erb @getA. /se t8e @getA sty e if:
08e - ass i7p e7ents a :a9a Bean. 08ere is a -orrespondin< @setA 7et8od. 08e resu t of t8e 7et8od -orresponds dire-t y to t8e 9a ue of an instan-e 9ari" ab e.
Rationale 08e @getA -on9ention is wide y a--epted by t8e :a9a -o77unity. 3 ample
totalTime getTotalTime get"ength validSuccesors
)u e (': %a7e 7et8ods settin< properties of an obDe-t (set 7et8ods) usin< t8e 9erb @setA. /se t8is -on9ention w8en:
08e - ass i7p e7ents a :a9a Bean. 08ere is a -orrespondin< @getA 7et8od. 08e 7et8odMs purpose is to set t8e 9a ue of an instan-e 9ariab e.
Rationale 08e @setA -on9ention is wide y a--epted by t8e :a9a -o77unity.
,.)
=ariable -ames
)u e (!: /se nouns to na7e 9ariab es and attributes. A 9ariab e na7e 7ust -orrespond to an En< is8 noun# potentia y a--o7panied by additiona words t8at furt8er des-ribe or - arify it. Rationale 3ariab es represent eit8er entities fro7 t8e rea wor d or di<ita entities used in" side a pro<ra7. In bot8 -ases# t8ose entities are referred to in natura an<ua<e us" in< nouns.
BSSC 2005(2) Issue 1.0 C1AP0E) 4 %A$I%5 3 ample

shipping=ddress counter current#osition maximal#ower
4>
,.)." !arameter -ames

)u e (=: F8en a -onstru-tor or @setA 7et8od assi<ns a para7eter to a fie d# <i9e t8at para7eter t8e sa7e na7e as t8e fie d. Rationale F8i e 8idin< t8e na7es of instan-e 9ariab es wit8 o-a 9ariab es is <enera y poor sty e# t8is parti-u ar -ase brin<s so7e benefits. /sin< t8e sa7e na7e re ie9es t8e pro<ra77er of t8e responsibi ity of -o7in< up wit8 a different na7e. It a so pro" 9ides a - ue to t8e reader t8at t8e para7eter 9a ue is destined for assi<n7ent to t8e fie d of t8e sa7e na7e. 3 ample
class(TestAacility( { ((((private(String(name, ((((public(TestAacility%String(name*( (((({ ((((((((this.name(-(name, ((((}( (end(method ((((public(set4ame(%String(name*( (((({ ((((((((this.name(-(name, ((((}( (end(method }( (end(class
,.).% #nstance =ariable -ames

)u e 40: Cua ify instan-e 9ariab e referen-es wit8 this to distin<uis8 t8e7 fro7 o" -a 9ariab es. Rationale 0o fa-i itate distin<uis8in< between o-a and instan-e 9ariab es# a ways Hua ify fie d 9ariab es usin< t8e this &eyword. 3 ample
public(class(=tomic=dder( { ((((private(int(count,
4'
((((public(=tomic=dder%int(count*( (((({ ((((((((this.count-count, ((((}( (end(method ((((public(synchroni$ed(int(fetch=nd=dd%int(value*( (((({ ((((((((int(temp(-(this.count, ((((((((this.count(.-(value, ((((((((return(temp, ((((}( (end(method ((((... }( (end(class
,.$
Constant -ames
)u e 41: /se upper"-ase etters for ea-8 word and separate ea-8 pair of words wit8 an unders-ore w8en na7in< :a9a -onstants. Rationale 08e -apita iEation of -onstant na7es distin<uis8es t8e7 fro7 ot8er non"fina 9ariab es: 3 ample
class(3yte( { ((((public(static(final(byte(2=>&G="JE(-(.60K, ((((public(static(final(byte(254&G="JE(-(/, ((((... }( (end(class
BSSC 2005(2) Issue 1.0 C1AP0E) 5 *.C/$E%0A0I.% A%* C.$$E%0I%5 C.%3E%0I.%S
4!
Chapter / Documentation and Commenting Conventions

/." #ntroduction
As dis-ussed e sew8ere in t8is do-u7ent# t8e fina and 7ost re iab e sour-e of infor7ation about a proDe-t is its own sour-e -ode. 1owe9er# sour-e -ode is often diffi-u t to interpret on its own# t8us 7a&in< it ne-essary to write additiona e;p anato" ry do-u7entation. A 9ery pra-ti-a way to &eep su-8 do-u7entation are -ode -o7" 7ents. *o-u7entation in -o77ents is <enera y easier to 7aintain# sin-e it is o-at" ed - oser to t8e do-u7ented -ode. It a so 7a&es it 7ore pra-ti-a to 7aintain t8e -ode itse f# be-ause it redu-es t8e need to refer to separate do-u7ents w8en under" standin< it. :a9a de9e opers 8a9e an additiona reason to do-u7ent t8eir -ode usin< -o7" 7ents: t8e :a9ado- too RS/%*o-S. :a9ado- ta&es as input a set of :a9a sour-e fi es# e;tra-ts infor7ation fro7 espe-ia y for7atted -o77ents in t8e7# and pro" du-es we stru-tured# -ross"referen-ed do-u7entation as a resu t. 08e :a9ado- ap" proa-8 -o7bines t8e pra-ti-a ity of &eepin< do-u7entation in -ode -o77ents wit8 t8e -on9enien-e of 8a9in< separate# 8i<8 e9e referen-e do-u7entation for t8e -ode interfa-es in a syste7. 08e ru es and re-o77endations in t8is -8apter are -on-erned wit8 8ow to write appropriate sour-e e9e do-u7entation for :a9a. Parti-u ar y# 7any of t8e ru es and re-o77endations 8a9e to do wit8 8ow to write -o77ents in su-8 a way t8at t8e :a9ado- too -an produ-e 8i<8 Hua ity referen-e do-u7entation fro7 t8e7.
/.%
Comment Types
08e :a9a pro<ra77in< an<ua<e supports t8ree -o77ent types:
A one" ine or end" ine -o77ent t8at be<ins wit8 @ t8e end of t8e ine.
A and -ontinues t8rou<8 to
A standard# or C"sty e# -o77ent# w8i-8 starts wit8 @ !A and ends wit8 @! A. A do-u7entation -o77ent t8at starts wit8 @ !!A and ends wit8 @! A. 08e :a9ado- too pro-esses on y -o77ents of t8is type.
/.*
Documenting the Detailed Design

+ecommen!ation 1% 7se !ocumentation comments to !escri1e programming interfaces 1efore implementing them$ Rationale 08e detai ed desi<n of a - ass interfa-e (as opposite to t8e detai ed desi<n of its
BSSC 2005(2) Issue 1.0 C1AP0E) 5 *.C/$E%0A0I.% A%* C.$$E%0I%5 C.%3E%0I.%S
4=
i7p e7entation) -onsists of t8e 7et8od si<natures# to<et8er wit8 t8eir spe-ifi-ations. An e;-e ent way to do-u7ent su-8 a desi<n is to write a s&e eton - ass definition# -onsistin< of t8e 7et8od de- arations (wit8 no -ode in t8eir bodies) and -orrespond" in< do-u7entation -o77ents spe-ifyin< t8e7. 08e best ti7e to write t8is do-u7en" tation is ear y in t8e de9e op7ent pro-ess# w8i e t8e purpose and rationa e for intro" du-in< t8e new - asses or interfa-es is sti fres8 in your 7ind. ,o owin< t8is pra-ti-e 7a&es it possib e to run :a9ado- in t8e ear iest sta<es of i7p e7entation# to produ-e do-u7ents t8at -an be used for re9iewin< t8e desi<n as we as for <uidin< t8e de9e opers i7p e7entin< it. Additiona y# t8is do-u7entation -onstitutes a so id basis for any fina API referen-e do-u7entation t8at 7ay need to be produ-ed.
/.,
Javadoc 0eneral Descriptions

)u e 42: Pro9ide a su77ary des-ription and o9er9iew for ea-8 app i-ation or <roup of pa-&a<es. 08e :a9ado- uti ity pro9ides a 7e-8anis7 for in- udin< a pa-&a<e"independent o9er9iew des-ription in t8e do-u7entation it <enerates. /se t8is -apabi ity to pro9ide an o9er9iew des-ription for ea-8 app i-ation or <roup of re ated pa-&a<es you -re" ate. 08e :a9ado- do-u7entation RS/%*o-S e;p ains 8ow to 7a&e use of t8is fea" ture. Rationale AdeHuate o9er9iew do-u7entation is funda7enta for pro<ra7 -o7pre8ension. )u e 4(: Pro9ide a su77ary des-ription and o9er9iew for ea-8 pa-&a<e. 08e :a9ado- uti ity pro9ides a 7e-8anis7 for in- udin< pa-&a<e des-riptions in t8e do-u7entation it <enerates. /se t8is -apabi ity to pro9ide a su77ary des-ription and o9er9iew for ea-8 pa-&a<e you -reate. 08e :a9ado- do-u7entation RS/%*o-S e;p ains 8ow to 7a&e use of t8is fea" ture. Rationale AdeHuate o9er9iew do-u7entation is funda7enta for pro<ra7 -o7pre8ension.
/./
Javadoc Comments
)u e 44: /se do-u7entation -o77ents to des-ribe t8e pro<ra77in< interfa-e. P a-e do-u7entation -o77ents in front of any - ass# interfa-e# 7et8od# -on" stru-tor# or fie d de- aration t8at appears in your -ode. Rationale 08ese -o77ents pro9ide infor7ation t8at t8e :a9ado- uti ity uses to <enerate 8yperte;t"based# referen-e# App i-ation Pro<ra77in< Interfa-e (API) do-u7entation.
BSSC 2005(2) Issue 1.0 C1AP0E) 5 *.C/$E%0A0I.% A%* C.$$E%0I%5 C.%3E%0I.%S )u e 45: *o-u7ent pub i-# prote-ted# pa-&a<e# and pri9ate 7e7bers.
50
Supp y do-u7entation -o77ents for a 7e7bers# in- udin< t8ose wit8 pa-&" a<e# prote-ted# and pri9ate a--ess. Rationale 08e de9e oper w8o 7ust understand your -ode before i7p e7entin< an en" 8an-e7ent or a defe-t fi; wi appre-iate your foresi<8t in pro9idin< Hua ity do-u7en" tation for a - ass 7e7bers# not Dust for t8e pub i- ones. )u e 4>: /se a sin< e -onsistent for7at and or<aniEation for a do-u7entation -o77ents. A proper y for7atted do-u7entation -o77ent -ontains a des-ription fo owed by one or 7ore :a9ado- ta<s. ,or7at ea-8 do-u7entation -o77ent as fo ows:
Indent t8e first ine of t8e -o77ent to a i<n t8e s as8 -8ara-ter of t8e start -o7" 7ent sy7bo @ !!A wit8 t8e first -8ara-ter in t8e ine -ontainin< t8e asso-iated definition. Be<in ea-8 subseHuent ine wit8in an asteris& @!A. A i<n t8is asteris& wit8 t8e first asteris& in t8e start -o77ent sy7bo . /se a sin< e spa-e to separate ea-8 asteris& fro7 any des-ripti9e te;t or ta<s t8at appear on t8e sa7e ine. Insert a b an& -o77ent ine between t8e des-ripti9e te;t and any :a9ado- ta<s t8at appear in t8e -o77ent b o-&. End ea-8 do-u7entation -o77ent b o-& wit8 t8e asteris& in t8e end -o77ent sy7bo @! A a i<ned wit8 t8e ot8er asteris&s in t8e -o77ent b o-&.
Rationale ,or7attin< -on9entions are ne-essary to a-8ie9e -ode unifor7ity. 3 ample

!! !(Descriptive text for this entity. ! !(Ltag(Descriptive text for this ta . !
)u e 4': Frap &eywords# identifiers# and -onstants 7entioned in do-u7entation -o77ents wit8 9codeM...9 codeM ta<s. %est &eywords# pa-&a<e na7es# - ass na7es# interfa-e na7es# 7et8od na7es# fie d na7es# para7eter na7es# -onstant na7es# and -onstant 9a ues t8at appear in a do-u7entation -o77ent wit8in 10$2 9codeM ...9 codeM 7ar&"up ta<s. Rationale 08e 9codeM ... 9 codeM ta<s te 10$2 browsers to render t8e -ontent in a sty e different fro7 t8at of nor7a te;t# so t8at t8ese e e7ents wi stand out.
BSSC 2005(2) Issue 1.0 C1AP0E) 5 *.C/$E%0A0I.% A%* C.$$E%0I%5 C.%3E%0I.%S 3 ample
!! !(=llocates(a(9codeMAlag9 codeM(object !(representing(the(9codeMvalue9 codeM(argument. !(... ! public(Alag%boolean(value*( { ((((... }( (end(method(
51
)u e 4!: Frap fu -ode e;a7p es appearin< in do-u7entation -o77ents wit8 9preM ... 9 preM ta<s. Rationale 08e 9preM ...9 preM ta<s are used to te 10$2 browsers to retain t8e ori<ina for7attin<# in- udin< indentation and ine ends# of t8e @prefor7attedA e e7ent. +ecommen!ation 13 Consi!er mar;ing the first occurrence of an i!entifier with a !"lin#$ tag$ Rationale Ea-8 pa-&a<e# - ass# interfa-e# 7et8od# and fie d na7e t8at appears wit8in a do-u7entation -o77ent 7ay be -on9erted into a 8yperte;t in& by rep a-in< its na7e wit8 an appropriate y -oded {Llin<} ta<. So7e - asses and 7et8ods are so freHuent y used and we &nown t8at it is not ne-essary to in& to t8eir do-u7entation e9ery ti7e t8ey are 7entioned. Create in&s on y w8en t8e do-u7entation asso-iated wit8 t8e referen-ed e e7ent wou d tru y be of interest or 9a ue to t8e reader. 08is 7a&es do-u7entation <enera y easier to read and 7aintain. )u e 4=: In- ude :a9ado- ta<s in a -o77ent in t8e fo owin< order: Lauthor Lparam Lreturn Lthrows Lsee Lsince Lserial Ldeprecated Rationale ,or7attin< -on9entions are ne-essary to a-8ie9e -ode unifor7ity. )u e 50: In- ude an Lauthor and a Lversion ta< in e9ery - ass or interfa-e de" s-ription. 2ist 7u tip e Lauthor ta<s in -8rono o<i-a order# wit8 t8e - ass or interfa-e
BSSC 2005(2) Issue 1.0 C1AP0E) 5 *.C/$E%0A0I.% A%* C.$$E%0I%5 C.%3E%0I.%S -reator isted first. Rationale 08is way# t8e 8istory of t8e fi e is easier to fo ow. )u e 51: ,u y des-ribe t8e si<nature of ea-8 7et8od.
52
08e do-u7entation for ea-8 7et8od s8a a ways in- ude a des-ription for ea-8 para7eter# ea-8 -8e-&ed e;-eption# any re e9ant un-8e-&ed e;-eptions# and any return 9a ue. In- ude a Lparam ta< for e9ery para7eter in a 7et8od. 2ist 7u tip e Lparam ta<s in para7eter de- aration order. In- ude a Lreturn ta< if t8e 7et8od returns any type ot8er t8an 9oid. In- ude an Lexception ta< for e9ery -8e-&ed e;-eption isted in a t8rows - ause. In- ude an Lexception ta< for e9ery un-8e-&ed e;-eption t8at a user 7ay reasonab y e;pe-t to -at-8. 2ist 7u tip e Lexception ta<s in a p8a" beti-a order of t8e e;-eption - ass na7es.. Sort 7u tip e Lsee ta<s a--ordin< to t8eir distan-e fro7 t8e -urrent o-ation# in ter7s of do-u7ent na9i<ation and na7e Hua ifi-ation. .rder ea-8 <roup of o9er oad" ed 7et8ods a--ordin< to t8e nu7ber of para7eters ea-8 a--epts# startin< wit8 t8e 7et8od t8at 8as t8e east nu7ber of para7eters:
!! !(... !(Lsee(Nfield !(Lsee(N1onstructor%* !(Lsee(N1onstructor%Type...* !(Lsee(1lass !(Lsee(1lassNfield !(Lsee(1lassN1onstructor%* !(Lsee(1lassN1onstructor%Type(...*
/.)
Comment Contents and Style

+ecommen!ation 14 6ocument precon!itions, post con!itions, an! in)ariant con!itions$ 08e pri7ary purpose for do-u7entation -o77ents is to define a pro<ra77in< -ontra-t between a - ient and a supp ier of a ser9i-e. 08e do-u7entation asso-iated wit8 a 7et8od s8ou d des-ribe a aspe-ts of be8a9ior on w8i-8 a -a er of t8at 7et8od -an re y and s8ou d not atte7pt to des-ribe i7p e7entation detai s. Rationale As pre-onditions# post -onditions# and in9ariants are t8e assu7ptions under w8i-8 you use and intera-t wit8 a - ass# do-u7entin< t8e7 is i7portant# espe-ia y if t8ese -onditions are too -ost y to 9erify usin< run"ti7e assertions.
BSSC 2005(2) Issue 1.0 C1AP0E) 5 *.C/$E%0A0I.% A%* C.$$E%0I%5 C.%3E%0I.%S +ecommen!ation 1# Inclu!e examples$ Rationale
5(
.ne of t8e easiest ways to e;p ain and understand 8ow to use software is by <i9in< spe-ifi- e;a7p es. /se t8e 10$2 9preM(...9 preM ta<s to <uarantee t8at t8e for7attin< of t8e e;a7p es is preser9ed in t8e fina do-u7entation. )u e 52: *o-u7ent syn-8roniEation se7anti-s. Rationale $et8ods de- ared as synchroni$ed wi be auto7ati-a y 7ar&ed as su-8 in :a9ado- <enerated do-u7entation. $et8ods not de- ared as synchroni$ed 7ay# 8owe9er# sti be t8read"safe# sin-e t8ey -ou d e;p i-it y i7p e7ent any needed t8read syn-8roniEation. In su-8 a situation# you 7ust indi-ate t8at t8e 7et8od is in" terna y syn-8roniEed in t8e -orrespondin< 7et8od do-u7entation. +ecommen!ation 12 7se @thisA rather than @theA when referring to instances of the current class$ F8en des-ribin< t8e purpose or be8a9ior of a 7et8od# use @thisA instead of @theA to refer to an obDe-t t8at is an instan-e of t8e - ass definin< t8e 7et8od. Rationale Co77ents written t8is way are 7ore a--urate and easier to for7u ate.
/.$
#nternal Comments
+ecommen!ation 1> 6ocument local )aria1les with an en!-line comment$ *o-u7ent a but tri9ia o-a 9ariab es wit8 end" ine -o77ents. Rationale 3ariab e do-u7entation is one of t8e 7ost 8e pfu aids to understand a pro" <ra7. 3 ample
int(i, float(current2ax,(((( (2aximal(value(seen(until(now.
)u e 5(: Add a @fa "t8rou<8A -o77ent between two -ase abe s# if no brea& state" 7ent separates t8ose abe s. F8en t8e -ode fo owin< a swit-8 state7entGs -ase abe does not in- ude a brea& but# instead# @fa s t8rou<8A into t8e -ode asso-iated wit8 t8e ne;t abe # add a -o77ent to indi-ate t8is was your intent. %ote t8at two adDa-ent abe s do not re" Huire an inter9enin< -o77ent. Rationale .t8er de9e opers 7ay eit8er in-orre-t y assu7e a brea& o--urs# or wonder
BSSC 2005(2) Issue 1.0 C1AP0E) 5 *.C/$E%0A0I.% A%* C.$$E%0I%5 C.%3E%0I.%S w8et8er you si7p y for<ot to -ode one. 3 ample
switch(%command*( { case(A=ST&AOR7=RH; ((((isAastAorward(-(true, (((( (Aall(through8 case(#"=O; case(AOR7=RH; ((((isAorward(-(true, ((((brea<, case(A=ST&RE754H; ((((isAastRewind(-true, (((( (Aall(through8 case(RE754H; ((((isRewind(-(true, ((((brea<(, }( (end(switch
54
)u e 54: 2abe e7pty state7ents. F8en a -ontro stru-ture# su-8 as a while or for oop# 8as an e7pty b o-& by desi<n# add a -o77ent to indi-ate t8at t8is was your intent. Rationale E7pty b o-&s 7ay be -onfusin< for pro<ra77ers tryin< to understand t8e -ode. $a&in< t8e7 e;p i-it 8e ps to pre9ent su-8 -onfusion. 3 ample
(Strip(leading(space while(%%c(-(Reader.read%**(--(S#=1E*( { (((( (Empty8 }( (end(while
)u e 55: /se end" ine -o77ents to e;p i-it y 7ar& t8e o<i-a ends of -onditiona s oops# e;-eptions# enu7erations# 7et8ods or - asses. 08e end" ine -o77ents 7ust 8a9e t8e for7at
(end(%#ey&ord'
w8ere %#ey&ord' is one of class# method# if# for# while# switch# constructor# interface# enum# try# or catch. Rationale 2ar<e y i7pro9es t8e readabi ity of -ode by 7a&in< -ontro stru-tures 7ore 9isi" b e. 3 ample See e;a7p es t8rou<8out t8is do-u7ent.
BSSC 2005(2) Issue 1.0 C1AP0E) > :A3A *ESI5% A%* P).5)A$$I%5 5/I*E2I%ES
55
Chapter ) Java Design and !rogramming 0uidelines

)." #ntroduction
08e e;perien-e of years of software de9e op7ent wit8 t8e :a9a pro<ra77in< an<ua<e as we as wit8 ot8er obDe-t oriented an<ua<es 8as eft a wide 9ariety of 9a uab e earned essons t8at -an be app ied in new proDe-ts to i7pro9e a 7ost e9ery aspe-t of t8e de9e op7ent wor&. 08e present -8apter su77ariEes a nu7ber of su-8 essons# e;p ainin<# w8ere ne-essary# t8eir parti-u ar re e9an-e to t8e :a9a an<ua<e and pro<ra77in< en9i" ron7ent.
).%
!ac@ages
A pa-&a<e is a -on-eptua unit -onsistin< of a set of fi es w8i-8 to<et8er i7p e" 7ent a -o e-tion of interfa-es and - asses. +ecommen!ation 10 7se separate pac;ages for each of the software components !efine! !uring the !esign phase$ 08e desi<n p8ase s8a brea& t8e o9era software syste7 into o<i-a -o7po" nents# as a 7eans of 7ana<in< t8e -o7p e;ity of t8e o9era syste7. Ea-8 one of t8ese -o7ponents s8ou d -orrespond to a :a9a pa-&a<e# proper y or<aniEed in a separate fi e syste7 dire-tory. Rationale ,o owin< t8is re-o77endation 7a&es t8e fi e stru-ture of t8e syste7 ref e-t its -on-eptua stru-ture. Puttin< separate -o7ponents into pa-&a<es a so 8e ps en-ap" su ation# sin-e t8e :a9a pro<ra77in< an<ua<e offers 7e-8anis7s to prote-t t8e i7" p e7entation of a pa-&a<e fro7 bein< a--essed by ot8er# e;terna pa-&a<es. +ecommen!ation 1? Place into the same pac;age t&pes that are commonl& use!, change!, an! release! together, or mutuall& !epen!ent on each other$ If a set of - asses and6or interfa-es are so - ose y -oup ed t8at you -annot use one wit8out usin< t8e ot8er# put t8e7 in t8e sa7e pa-&a<e. So7e e;a7p es of - ose y re ated types in- ude:
Containers and iterators. *atabase tab es# rows# and -o u7ns. Ca endars# dates# and ti7es. Points# ines# and po y<ons.
5>
Co7bine - asses t8at are i&e y to -8an<e at t8e sa7e ti7e for t8e sa7e rea" sons into a sin< e pa-&a<e. If two - asses are so - ose y re ated t8at -8an<in< one of t8e7 <enera y in9o 9es -8an<in< t8e ot8er# p a-e t8e7 in t8e sa7e pa-&a<e. Rationale Pa-&a<es are effe-ti9e units of reuse and re ease. Effe-ti9e reuse reHuires tra-&in< of re eases fro7 a -8an<e -ontro syste7. A pa-&a<e re ease -aptures t8e atest 9ersion of ea-8 - ass and interfa-e. +ecommen!ation %0 8)oi! c&clic pac;age !epen!encies$ 0a&e steps to e i7inate -y- i- dependen-ies between pa-&a<es# eit8er by -o7" binin< 7utua y dependent pa-&a<es or by introdu-in< a new pa-&a<e of abstra-" tions t8at 7any pa-&a<es -an depend on. Rationale Cy- i- dependen-ies 7a&e syste7s 7ore fra<i e and -an 7a&e para e de9e " op7ent (i.e.# de9e op7ent of 7any pa-&a<es by 7any de9e opers or tea7s wor&in< si7u taneous y) 7u-8 7ore diffi-u t. +ecommen!ation %1 Isolate )olatile classes an! interfaces in separate pac;ages$ Separate 9o ati e - asses fro7 stab e - asses to redu-e t8e -ode footprint af" fe-ted by new re eases# t8ereby redu-in< t8e i7pa-t on users of said -ode. A9oid p a-in< 9o ati e - asses or interfa-es in t8e sa7e pa-&a<e wit8 stab e - asses or in" terfa-es. Rationale .t8erwise# w8en usin< pa-&a<es as t8e unit of re ease# ea-8 ti7e a pa-&a<e is re eased# t8e users 7ust absorb t8e -ost of reinte<ratin< and retestin< a<ainst a t8e - asses in t8e pa-&a<e# a t8ou<8 7any 7ay not 8a9e -8an<ed. +ecommen!ation %% 8)oi! ma;ing pac;ages that are !ifficult to change !epen!ent on pac;ages that are eas& to change$ *o not 7a&e a pa-&a<e depend on ess stab e pa-&a<es. If ne-essary# -reate new abstra-tions t8at -an be used to in9ert t8e re ations8ip between t8e stab e -ode and t8e unstab e -ode. Rationale *ependen-ies between pa-&a<es s8ou d be oriented in t8e dire-tion of in-reas" in< stabi ity. A pa-&a<e s8ou d on y depend on pa-&a<es t8at are as stab e# or 7ore stab e# t8an itse f. +ecommen!ation %3 BaximiCe a1straction to maximiCe sta1ilit&$ Separate abstra-t - asses and interfa-es fro7 t8eir -on-rete -ounterparts to for7 stab e and unstab e pa-&a<es. Rationale 08e 7ore abstra-t a pa-&a<e is# t8e 7ore stab e it is.
5'
+ecommen!ation %4 Capture high-le)el !esign an! architecture as sta1le a1stractions organiCe! into sta1le pac;ages$ *efine pa-&a<es t8at -apture t8e 8i<8" e9e abstra-tions of t8e desi<n. P a-e t8e detai ed i7p e7entation of t8ose abstra-tions into separate pa-&a<es t8at de" pend on t8e 8i<8" e9e abstra-t pa-&a<es. Rationale 0o p an and 7ana<e a software de9e op7ent effort su--essfu y# t8e top" e9e desi<n 7ust stabi iEe Hui-& y and re7ain t8at way. )u e 5>: *o not use t8e wil!car! (@!A) notation in import state7ents. :a9a import state7ents 8a9e two possib e for7s. 08e first one i7ports a sin" < e - ass into t8e o-a 7odu eMs na7e spa-e# i.e.:
import(java.util.Gector,
08e se-ond one i7ports a - asses fro7 a <i9en pa-&a<e into t8e o-a 7od" u eMs na7e spa-e# i.e.:
import(java.util.!,
08is se-ond for7 7ust be a9oided. Rationale E;p i-it y i7portin< - asses 7a&es it 7u-8 easier to &now w8i-8 pa-&a<e a - ass -o7es fro7. Additiona y# sin-e two separate pa-&a<es -ou d 8a9e - asses or interfa-es of t8e sa7e na7e (i.e. java.util."ist and java.awt."ist) import state7ents usin< t8e wi d-ard notation -an ead to na7e -onf i-ts. )u e 5': Put a s8ared - asses and interfa-es t8at are interna to a proDe-t in a sep" arate pa-&a<e -a ed @internalA. C asses and interfa-es t8at are internal to a proDe-t# t8at is# t8at are not part of t8e proDe-tMs pub i- interfa-e# and t8at are s8ared a7on< ot8er pa-&a<es in t8e proDe-t# 7ust be put in a separate pa-&a<e -a ed @internalA. C asses in t8e inter" na pa-&a<e -ou d be free y stru-tured in ot8er pa-&a<es. Rationale Interna - asses t8at are s8ared a7on< two or 7ore pa-&a<es 7ust 7e de" - ared public# in order to 7a&e t8e s8arin< possib e at a . 08is 8as t8e side"effe-t of 7a&in< t8e7 a--essib e a so to e;terna users of t8e proDe-t. Puttin< t8e7 in a separate# internal pa-&a<e# 7a&es it - ear t8at t8ey are not part of t8e offi-ia in" terfa-e of t8e syste7 and s8ou d not be used outside it. )u e 5!: $a&e - asses t8at do not be on< to a pa-&a<eMs pub i- API private. Rationale 08is <uarantees t8at t8ese - asses wi not be a--essed by e;terna - ients# and e;- udes t8e7 fro7 t8e pub i- do-u7entation.
BSSC 2005(2) Issue 1.0 C1AP0E) > :A3A *ESI5% A%* P).5)A$$I%5 5/I*E2I%ES +ecommen!ation %# Consi!er using <a)a interfaces instea! of classes for the pu1lic 8PI of a pac;age$ Rationale
5!
$a&in< interfa-es public instead of t8eir -orrespondin< - asses 7a&es it easi" er to -8an<e t8e i7p e7entation ater on# w8i e &eepin< t8e interna API stab e.
).*
0eneral Class 0uidelines

)u e 5=: $a&e a - ass attributes private. Rationale $a&in< attributes private ensures -onsisten-y of 7e7ber data# sin-e on y t8e ownin< - ass 7ay -8an<e it. If ne-essary# a - ass -an pro9ide a--ess to se e-ted 7e7ber data by definin< appropriate pub i- a--essor 7et8ods. 08is pra-ti-e a-tua y 8ides t8e under yin< - ass i7p e7entation# 7a&in< it pos" sib e to transparent y -8an<e it wit8out affe-tin< t8e e;terna - ass interfa-e. 08e re" su t is t8at -ode dependin< on t8e - ass does not need to -8an<e w8en interna de" tai s of a - ass are 7odified. If attributes were pub i-# dire-t uses of t8e7 in ot8er parts of t8e syste7 wou d 8a9e to be adapted# wit8 t8e -onseHuent additiona effort and in-reased ris& of introdu-in< defe-ts. 3 ample 08e - assi- e;a7p e is a - ass representin< -o7p e; nu7bers# w8i-8 offers a-" -essor routines for t8e rea and i7a<inary parts of t8e -o7p e; nu7ber# as we as a--essor routines for t8e 7odu us and ar<u7ent of t8e -o7p e; nu7ber. C ass users do not need to &now w8i-8 representation is used interna y. If t8e attributes are 8idden# any intera-tion between t8e attributes -an be stri-t y -ontro ed wit8in t8e - ass itse f so t8at t8ey are <uaranteed to be in a -onsistent state# t8ereby redu-in< t8e a7ount of -8e-&in< -ode t8at is needed before t8eir 9a " ues are used e sew8ere. 3 ample
class(1Range( { (((( (5nvariant;(lower"imit(9-(upper"imit
((((private(int(lower"imit, ((((private(int(upper"imit, ((((public(void(set"imits%int(lower"imit'(int(upper"imit*( { ((((((((if(%lower"imit(9-(upper"imit*( (((((((({ ((((((((((((this.lower"imit(-(lower"imit, ((((((((((((this.upper"imit(-(upper"imit, ((((((((}( (end(if ((((((((else(
(((((((({ ((((((((((((this.lower"imit(-(upper"imit, ((((((((((((this.upper"imit(-(lower"imit, ((((((((}( (end(else ((((}( (end(else }( (end(class
5=
In t8e e;a7p e abo9e t8e pro<ra77er w8o uses t8is - ass does not 8a9e a-" -ess to t8e indi9idua attributes and is for-ed to use t8e set"imits%* 7et8od# w8i-8 <uarantees t8at t8e i7its are -onsistent. +ecommen!ation %2 Consi!er !eclaring classes representing fun!amental !ata t&pes as final$ Rationale *e- arin< a - ass as final a ows its 7et8ods to be in9o&ed 7ore effi-ient y. Si7p e - asses representin< funda7enta data types su-8 as# for e;a7p e# a 1omplex4umber - ass in an en<ineerin< pa-&a<e# often find widespread use wit8in t8eir tar<et do7ain. In su-8 a -ase# effi-ien-y -an be-o7e an issue of i7portan-e. .f -ourse# de- arin< your - ass as fina wi pro8ibit its use as a super- ass. %e9ert8e ess# t8ere is se do7 any reason to e;tend a - ass t8at i7p e7ents a funda" 7enta data type. In 7ost su-8 -ases# obDe-t -o7position is a 7ore appropriate 7e-8anis7 for reuse. +ecommen!ation %> $+e!uce the siCe of classes an! metho!s 1& refactoring$ Rationale S7a er - asses and 7et8ods are easier to desi<n# -ode# test# do-u7ent# read# understand# and use. Be-ause s7a er - asses <enera y 8a9e fewer 7et8ods and represent si7p er -on-epts# t8eir interfa-es tend to e;8ibit better -o8esion. If a - ass or 7et8od see7s too bi<# -onsider refa-torin< t8at - ass or 7et8od into additiona - asses or 7et8ods. +ecommen!ation %0 8)oi! inheritance across pac;ages, rel& on interface implementation instea!$ Rationale In8eritan-e (as a-8ie9ed by usin< t8e extends &eyword) -auses a stron< -ou" p in< between a base - ass and its sub- asses. Any -8an<e to t8e base - ass 7ay <enerate unwanted be8a9ior in t8e in8eritan-e tree of sub- asses. A t8ou<8 t8is sort of -oup in< is often to erab e inside a sin< e pa-&a<e# it -an -ause prob e7s in a ar<er syste7. In8eritan-e s8ou d be a9oided not on y to redu-e -oup in<# but to pre9ent t8e so"-a ed fra<i e base - ass prob e7. Base - asses are -onsidered fra<i e w8en t8ey -an be 7odified in a see7in< y safe way# but t8eir new be8a9ior# if in8erited by de" ri9ed - asses# 7i<8t -ause t8e7 to 7a fun-tion. So# deri9ed - asses as we as base - asses 7ust be tested for t8e new be8a9ior. , e;ibi ity is ost be-ause e;p i-it use of -on-rete - asses na7es o-&s you into spe-ifi- i7p e7entations# 7a&in< down"t8e" ine -8an<es unne-essari y diffi-u t. Pro" <ra77in< to interfa-es is at t8e -ore of f e;ib e stru-ture.
>0
A t8ese disad9anta<es -an be a9oided by re yin< on interfa-e i7p e7entation# as t8e 7aDority of desi<n patterns R5A$S do. 08e fo owin< e;a7p e de7onstrates t8is: 3 ample
interface(Stac<( { ((((void(push%Object(o*, ((((Object(pop%*, ((((void(push2any%ObjectPQ(source*, }( (end(interface class(SimpleStac<(implements(Stac<( { ((((private(int(stac<#ointer, ((((private(ObjectPQ(stac<, ((((public(Stac<%*( (((({ ((((((((stac<#ointer(-(:6, ((((((((stac<(-(new(ObjectP6///Q, ((((}( (end(constructor ((((public(void(push%Object(o*( (((({ ((((((((assert(stac<#ointer(9(stac<.length:6, ((((((((..stac<#ointer, ((((((((stac<Pstac<#ointerQ(-(o, ((((}( (end(method ((((public(Object(pop%*( (((({ ((((((((assert(stac<#ointer(M-(/, ((((((((stac<#ointer::, ((((((((return(stac<Pstac<#ointer.6Q, ((((}( (end(method ((((public(void(push2any%ObjectPQ(source*( (((({ ((((((((assert(%stac<#ointer(.(source.length*(9(stac<.length, ((((((((System.arraycopy%source'(/'(stac<'(stac<#ointer(.(6' (((((((((((((((((((((((((source.length*, ((((((((stac<#ointer(.-(source.length, ((((}( (end(method }( (end(class class(2onitorableStac<(implements(Stac<( { ((((private(int(highSi$e2ar<, ((((private(int(currentSi$e, ((((SimpleStac<(stac<, ((((public(2onitorableStac<%*(
(((({ ((((((((highSi$e2ar<(-(/, ((((((((stac<(-(new(SimpleStac<%*, ((((}( (end(constructor ((((public(void(push%Object(o*( (((({ ((((((((..currentSi$e, ((((((((if(%currentSi$e(M(highSi$e2ar<*( (((((((({ ((((((((((((highSi$e2ar<(-(currentSi$e, ((((((((}( (end(if ((((((((stac<.push%o*, ((((}( (end(method ((((public(Object(pop%*( (((({ ((((((((::currentSi$e, ((((((((return(stac<.pop%*, ((((}( (end(method ((((public(void(push2any%ObjectPQ(source*( (((({ ((((((((currentSi$e(.-(source.length, ((((((((if(%currentSi$e(.(source.length(M(highSi$e2ar<*( (((((((({ ((((((((((((highSi$e2ar<(-(currentSi$e(.(source.length, ((((((((}( (end(if ((((((((stac<.push2any%source*, ((((}( (end(method ((((public(int(maximumSi$e%*( (((({ ((((((((return(highSi$e2ar<, ((((}( (end(method }( (end(class
>1
Sin-e t8e two i7p e7entations 7ust pro9ide 9ersions of e9eryt8in< in t8e pub iinterfa-e# it is 7u-8 7ore diffi-u t to <et t8in<s wron<.
).,
-ested Classes& #nner Classes& and 5nonymous Classes

An inner - ass is a nested - ass w8ose instan-e e;ists wit8in an instan-e of its en- osin< - ass and 8as dire-t a--ess to t8e instan-e 7e7bers of its en- osin< in" stan-e. An inner - ass is a non"stati- nested - ass. Inner - asses are used pri7ari y to i7p e7ent adapter - asses. Vou -an a so de- are an inner - ass wit8out na7in< it. 08is is a so"-a ed anon&mous - ass. +ecommen!ation %? 9imit the use of anon&mous classes$ 2i7it t8e use of anony7ous - asses to - asses t8at are 9ery s7a (no 7ore t8an a 7et8od or two) and w8ose use is we understood (i.e. AF0 e9ent 8and in< adapter - asses or Enumerator - asses).
BSSC 2005(2) Issue 1.0 C1AP0E) > :A3A *ESI5% A%* P).5)A$$I%5 5/I*E2I%ES Rationale
>2
Anony7ous - asses -an 7a&e -ode diffi-u t to read and# for t8is reason# its use s8ou d be redu-ed to a 7ini7u7. 3 ample
public(class(Stac<( (((({ ((((private(Gector(items, (((( (Stac<Fs(methods(and(constructors ((((... ((((public(Enumeration(enumerator%*( (((({ ((((((((return(new(Enumeration%*( (((((((({ ((((((((((((int(current5tem(-(items.si$e%*(:(6, ((((((((((((public(boolean(has2oreElements%*( (((((((((((({ ((((((((((((((((return(%current5tem(M-(/*, ((((((((((((}( (end(method ((((((((((((public(Object(nextElement%*( (((((((((((({ ((((((((((((((((if(%8has2oreElements%**( (((((((((((((((({ ((((((((((((((((((((throw(new(4oSuchElementException%*, ((((((((((((((((}( (end(if ((((((((((((((((else( (((((((((((((((({ ((((((((((((((((((((return(items.element=t%current5tem::*, ((((((((((((((((}( (end(else ((((((((((((}( (end(method ((((((((}( (end(method ((((}( (end(method }( (end(class
)./
Constructors and 8bAect Lifecycle

Constru-tors are needed to -reate new obDe-ts and initia iEe t8e7 to a 9a id state. Constru-tors 8a9e a ar<e i7pa-t on perfor7an-e. 5ood -odin< ru es# espe" -ia y to 7ini7iEe t8eir use# are i7portant for we perfor7in< app i-ations. )u e >0: A - ass s8a define at east one -onstru-tor. Rationale 08e defau t -onstru-tor# i.e.# t8e one wit8 no ar<u7ents# is auto7ati-a y pro9id" ed by t8e -o7pi er if no ot8er -onstru-tors are e;p i-it y de- ared. 08e defau t -on" stru-tor supp ied by t8e -o7pi er wi initia iEe data 7e7bers to null or eHui9a ent 9a ues. ,or 7any - asses# t8is 7ay not be an a--eptab e be8a9ior.
>(
)u e >1: 1ide any -onstru-tors t8at do not -reate 9a id instan-es of t8e -orrespond" in< - ass# by de- arin< t8e7 as protected or private. If a -onstru-tor produ-es - ass in9a id instan-es (i.e.# - ass instan-es t8at do not -o7p y wit8 t8e - ass in9ariant)# 8ide it by de- arin< it as protected or private. Rationale Pub i- -onstru-tors are a ways e;pe-ted to return 9a id instan-es. Constru-tors t8at do not return 9a id instan-es are on y -on-ei9ab e as a 7eans for i7p e7entin< 8i<8er e9e fun-tiona ity in - ass# and for t8at reason s8ou d a ways be 8idden. )u e >2: *o not -a non"fina 7et8ods fro7 wit8in a -onstru-tor. Rationale Sub- asses 7ay o9erride non"fina 7et8ods. :a9aMs runti7e syste7 dispat-8es -a s to su-8 7et8ods a--ordin< to t8e a-tua type of t8e -onstru-ted obDe-t# before e;e-utin< t8e deri9ed - ass -onstru-tor. 08is 7eans t8at w8en t8e -onstru-tor in" 9o&es t8e deri9ed 7et8od# t8e instan-e 9ariab es be on<in< to t8e deri9ed - ass 7ay sti be in an in9a id state. 0o pre9ent t8is situation fro7 8appenin<# -a on y fina 7et8ods fro7 t8e -onstru-tor. +ecommen!ation 30 8)oi! creating unnecessar& o1:ects$ Rationale Be-ause of t8e -o7p e; 7e7ory 7ana<e7ent operations it in9o 9es# obDe-t -reation is an e;pensi9e pro-ess. Creatin< an obDe-t not on y i7p ies a o-atin< its 7e7ory# but a so ta&in< -are of re easin< it ater. Sin-e t8e :a9a pro<ra77in< an" <ua<e pro9ides an auto7ati- <arba<e -o e-tor t8at operates transparent y# :a9a pro<ra77ers often for<et t8at <arba<e -o e-tion -y- es are e;pensi9e# and t8at t8ey -an serious y in-rease t8e o9era oad of a syste7. It is often possib e to rationa iEe t8e data stru-tures in a pro<ra7 to use ess ob" De-ts. A so# situations reHuirin< ar<e nu7bers of obDe-ts to be -reated on y to be dis" -arded soon (i.e.# nodes of a dyna7i-a y a o-ated Hueue in a networ& app i-ation) -an be 8and ed by -o e-tin< dis-arded obDe-ts in an additiona data stru-ture and reusin< t8e7 w8en needed. +ecommen!ation 31 8)oi! using the ne& ;e&wor! !irectl&$ Rationale ,ro7 an obDe-t"oriented desi<n point of 9iew# t8e new &eyword 8as two serious disad9anta<es:
It is not po y7orp8i-. /sin< new i7p ies referen-in< a -on-rete - ass e;p i-it y by na7e. 4ew -annot dea wit8 situations w8ere obDe-ts of different - asses 7ust be -reated dependin< on dyna7i- -onditions. It fai s to en-apsu ate obDe-t -reation. Situations w8ere obDe-ts -ou d be -reated on y optiona y -annot be proper y 8and ed wit8 new.
>4
Proper y 8and in< t8ese drawba-&s is# 8owe9er# possib e. A nu7ber of desi<n patterns# i&e stati- fa-tory 7et8ods# abstra-t fa-tories# and prototypes R5A$S -an be used to en-apsu ate obDe-t -reation to 7a&e it 7ore f e;ib e and s-a ab e. Criti-a syste7s 8a9e spe-ia ru es for 7e7ory a o-ation# t8at 7ay supersede t8is re-o77endation. +ecommen!ation 3% Consi!er the use of static factor& metho!s instea! of constructors$ Rationale Stati- fa-tory 7et8ods are stati- - ass 7et8ods t8at return new obDe-ts of t8e - ass. A7on< t8eir ad9anta<es# wit8 respe-t to -onstru-tors# are: 08ey -an 8a9e des-ripti9e na7es. 08is is parti-u ar y usefu w8en you need to 8a9e a 9ariety of different -onstru-tors t8at differ on y in t8e para7eter ist. 08ey do not need to -reate a new obDe-t e9ery ti7e t8ey are in9o&ed (t8at is# t8ey en-apsu ate obDe-t -reation). 08ey -an return an obDe-t of any subtype of t8eir return type (t8at is# t8ey are po y" 7orp8i-). +ecommen!ation 33 7se neste! constructors to eliminate re!un!ant co!e$ Rationale 0o a9oid writin< redundant -onstru-tor -ode# -a 8i<8er" e9e -onstru-tors. 3 ample 08is -ode i7p e7ents t8e sa7e ow" e9e initia iEation in two different p a-es:
class(EDuipment( { ((((private(String(name, ((((private(double(balance, ((((private(final(static(double(HEA=J"T&3="=41E(-(/./d, ((((EDuipment%String(name'(double(balance*( (((({ ((((((((this.name(-(name, ((((((((this.balance(-(balance, ((((}( (end(constructor ((((EDuipment%String(name*( (((({ ((((((((this.name(-(name, ((((((((this.balance(-(HEA=J"T&3="=41E, ((((}( (end(constructor }( (end(class
ower" e9e -onstru-tors fro7
08is -ode i7p e7ents t8e sa7e ow" e9e initia iEation in one p a-e on y:
class(EDuipment(
{ ((((private(final(static(double(HEA=J"T&3="=41E(-(/./d, ((((private(String(name, ((((private(double(balance,
>5
((((EDuipment%final(String(name'(final(double(balance*( (((({ ((((((((this.name(-(name(, ((((((((this.balance(-(balance, ((((}( (end(constructor ((((EDuipment%final(String(name*( (((({ ((((((((this%name'(HEA=J"T&3="=41E*(, ((((}( (end(constructor }( (end(class
08is approa-8 is a so 8e pfu w8i e 9a idatin< para7eters# as it typi-a y redu-es t8e nu7ber of p a-es a <i9en -onstru-tor ar<u7ent appears. +ecommen!ation 34 7se laC& initialiCation$ *o not bui d so7et8in< unti you need it. If an obDe-t 7ay not be needed durin< t8e nor7a -ourse of t8e pro<ra7 e;e-ution# t8en do not bui d t8e obDe-t unti it is re" Huired. /se an a--essor 7et8od to <ain a--ess to t8e obDe-t. A users of t8at obDe-t# in- udin< wit8in t8e sa7e - ass# 7ust use t8e a--essor to <et a referen-e to t8e ob" De-t. Rationale 2aEy initia iEation 7a&es 7e7ory use 7ore effi-ient. 3 ample
class(Satellite( { ((((private(=ocsSubsystem(aocsSubsystem(, ((((Satellite%*( (((({ ((((((((this.aocsSubsystem(--(null(, ((((}( (end(constructor ((((=ocsSubsystem(get=ocsSubsystem%*( (((({ ((((((((if(%this.aocsSubsystem(--(null*( (((((((({ ((((((((((((this.aocsSubsystem(-(new(=ocsSubsystem%*, ((((((((}( (end(if ((((((((return(this.aocsSubsystem, ((((}( (end(constructor }( (end(class
>>
).)
;ethods
08e :a9a pro<ra77in< an<ua<e 8as 9ery spe-ifi- re-o77endations and ru es for 7et8ods# t8e 7us- es of t8e -ode w8ere t8e rea pro-essin< is defined. So7e of t8ese ru es and re-o77endations are re ated to perfor7an-e# ot8ers are re ated to <ood obDe-t oriented pro<ra77in< pra-ti-e# an<ua<e -onstru-ts6&eywords# or t8e use of t8reads. +ecommen!ation 3# +efrain from using the instanceof operator$ +el& on pol&morphism instea!$ *o not use instanceof to -8oose be8a9ior dependin< upon t8e obDe-tGs type. I7p e7ent# instead# obDe-t"spe-ifi- be8a9ior in 7et8ods deri9ed fro7 an appropriate base - ass or interfa-e. Rationale C8oi-es based on instanceof 7ust be 7odified e9ery ti7e t8e set of -8oi-e obDe-t types -8an<es# eadin< to britt e -ode. I7p e7entations based on po y7or" p8is7# on t8e ot8er 8and# enab e - ients to intera-t wit8 t8e base abstra-tion wit8out reHuirin< any &now ed<e of t8e deri9ed - asses. 08is 7a&es it possib e to introdu-e new - asses wit8out 7odifyin< t8e - ient. )u e >(: $et8ods t8at do not 8a9e to a--ess instan-e 9ariab es s8a be de- ared static. Rationale If a 7et8od does not reHuire a--ess to t8e state of an instan-e# i.e.# it neit8er reads nor writes any instan-e 9ariab es# it 7ust be de- ared static. 3 ample
double(static(middle%final(double(x6'(final(double(x0*( { ((((return(%x6(.(x0*( (0, }( (end(method
)u e >4: A para7eter t8at is not -8an<ed by t8e 7et8od s8a be de- ared final. Rationale 08e -o7pi er s8ou d be used to trap as 7any potentia prob e7s as possib e. *e- arin< para7eters t8at are 7eant to re7ain un-8an<ed as final wi 7a&e t8e -o7pi er issue a warnin< if t8ey are 7odified inad9ertent y. 08e final de- aration a so pro9ides t8e -o7pi er wit8 infor7ation t8at poten" tia y a ows it to opti7iEe t8e -ode in ways t8at wou d not be possib e ot8erwise.
).$
Local =ariables and 3 pressions

E;pressions are t8e wor&8orse of an app i-ation. Codin< ru es and re-o77en" dations for e;pressions are needed in e9ery -odin< an<ua<e. 08e -odin< ru es for t8e :a9a pro<ra77in< an<ua<e re ated to e;pressions are 9ery si7i ar to t8ose for ot8er pro<ra77in< an<ua<es.
BSSC 2005(2) Issue 1.0 C1AP0E) > :A3A *ESI5% A%* P).5)A$$I%5 5/I*E2I%ES +ecommen!ation 32 7se local )aria1les for one purpose onl&$ Rationale
>'
Pro<ra77ers often @re-y- eA o-a 9ariab es# by usin< t8e7 for different purpos" es in different parts of a -o7p e; 7et8od (i.e.# a sin< e int 9ariab e is used as -ounter for two tota y independent oops). /nfortunate y# t8is pra-ti-e -an -ause -onfusion w8en 7odifyin< t8e pro<ra7# and e9en ead to errors diffi-u t to spot. *efinin< a new o-a 9ariab e for e9ery separate tas& not on y 7a&es -ode - ear" er and easier to 7aintain# but -an be as effi-ient as usin< a sin< e 9ariab e# sin-e 7ost opti7iEin< -o7pi ers wi transparent y a o-ate 7e7ory on y for t8e o-a 9ari" ab es t8at are needed at a parti-u ar -ode spot. +ecommen!ation 3> +eplace repeate! non-tri)ial expressions with e"ui)alent metho!s$ ,a-tor out -o77on fun-tiona ity and repa-&a<e it as a 7et8od or a - ass. Rationale *oin< t8is 7a&es -ode potentia y easier to earn and understand. C8an<es are o-a iEed# t8us redu-in< 7aintenan-e and testin< effort. +ecommen!ation 30 Consi!er using the Strin (uffer class when concatenating strings$ Rationale Con-atenatin< :a9a strin<s is a re ati9e y e;pensi9e operation# be-ause it a " ways in9o 9es -reatin< a new obDe-t to store t8e resu t. A <orit87s t8at re y on per" for7in< ar<e nu7bers of -on-atenation operations 7ay in-ur ar<e perfor7an-e pena ties if t8ey are not i7p e7ented -arefu y. 08e standard String3uffer - ass was desi<ned wit8 t8is prob e7 in 7ind. String3uffer obDe-ts are dyna7i-a y <rowin< te;t buffers t8at -an 8and e an ar" bitrary nu7ber of -on-atenations wit8out -reatin< any new obDe-ts. /sin< t8e7 prop" er y -an ead to ar<e perfor7an-e i7pro9e7ents in te;t pro-essin< a <orit87s. )u e >5: /se parent8eses to e;p i-it y indi-ate t8e order of e;e-ution of nu7eri-a operators . Rationale 08e defau t ru es for order of e;e-ution of nu7eri-a operators as defined by t8e :a9a Pro<ra77in< 2an<ua<e differ so7eti7es fro7 t8ose traditiona y used in 7at8" e7ati-s. /sa<e of parent8esis is t8us ob i<atory# in order to 7a&e e;p i-it t8e order intended by t8e de9e oper.
).+
0enerics and Casting

5eneri-s are a feature introdu-ed to t8e :a9a pro<ra77in< an<ua<e durin< t8e :*Q 5.0 de9e op7ent -y- e# si7i ar in spirit to C?? te7p ates. 08ey are parti-u ar y
>!
usefu for i7p e7entin< <eneri- -o e-tion - asses (-ontainers) su-8 as trees# 9e-" tors# in&ed ists# and 8as8 7aps. In doin< so# t8ey 7a&e it possib e to a9oid t8e pro" -ess of -astin<# w8i-8 is 8i<8 y error"prone and potentia y ineffi-ient# sin-e -asts 7ust a ways be -8e-&ed dyna7i-a y for type -o7patibi ity. 08e use of <eneri-s is 8i<8 y re-o77ended and is a ways preferab e o9er t8e -astin< 7e-8anis7. 5eneri- - asses are# in rea ity# not as strai<8tforward as t8ey 7i<8t at first ap" pear# espe-ia y w8en tryin< to pro9ide true <eneri-ity. 08e desi<n of a <eneri- - ass needs so7e foret8ou<8t# as t8at of any - ass w8i-8 is used as a te7p ate para7e" ter. +ecommen!ation 3? 7se the enhance! for control structure an! generics where)er possi1leDapplica1le$ Rationale 08ese features of t8e :a9a pro<ra77in< an<ua<e not on y 7a&e -ode si7p er and easier to read# but safer and potentia y 7ore effi-ient. 08ey -onstitute an e;-e " ent way of produ-in< 8i<8 y reusab e -ode. 3 ample ,irst an e;a7p e t8at iterates o9er a -o e-tion# wit8out usin< any of t8e fea" tures:
void(cancel=ll%collection(c*( { ((((for(%5terator(i(-(c.iterator%*,(i.has4ext%*,* (((({ ((((((((TimerTas<(tt(-(%TimerTas<*(i.next%*, ((((((((tt.cancel%*, ((((}( (end(for }( (end(method
08e new way as i ustrated be ow is s8orter# 7ore readab e and easier to under" stand:
void(cancel=ll%1ollection9TimerTas<M(c*( { ((((for(%TimerTas<(tas<(;(c*( (((({ ((((((((tas<.cancel%*, ((((}( (end(for }( (end(method
)u e >>: /se <eneri-s instead of -astin< w8en na9i<atin< t8rou<8 -o e-tions. 08e ori<ina :a9a 7et8od of -astin< si7p e 9ariab es fro7 one type to anot8er is sti a9ai ab e in newer 9ersions# but its use is stron< y dis-oura<ed. Rationale Casts -an fai at run ti7e and often 7a&e -ode unreadab e. 3 ample A 7et8od i7p e7ented usin< t8e traditiona -ast 7e-8anis7:
static(void(expurgate%1ollection(c* { ((((for(%5terator(i(-(c.iterator%*,(i.has4ext%*,* (((({ ((((((((String(s(-(%String*(i.next%*, ((((((((if(%s.length%*(--(+*( (((((((({ ((((((((((((i.remove%*, ((((((((}( (end(if ((((}( (end(for }( (end(method
>=
Casts instru-t t8e -o7pi er to o9erride any type of infor7ation about an e;pres" sion. 5eneri-s s8ou d be used instead as out ined be ow:
static(void(expurgate%1ollection9StringM(c*( { ((((for(%5terator9StringM(i(-(c.iterator%*,(i.has4ext%*,(*( (((({ ((((((((if(%i.next%*.length%*(--(+*( (((((((({ ((((((((((((i.remove%*, ((((((((}( (end(if ((((}( (end(for }( (end(method
It is now - ear fro7 t8e 7et8od si<nature t8at t8e input -o e-tion is on y a owed to -ontain strin<s. A - ient pro<ra7 tryin< to pass in# for e;a7p e# a -o e-tion of strin< buffers# wou d not e9en -o7pi e. 08is wou d not be t8e -ase wit8 t8e -ast" based i7p e7entation# w8i-8 wou d on y fai at run"ti7e.
)..
Constants and 3numerated Types

+ecommen!ation 40 Be careful when using the import static feature to !efine glo1al constants$ Rationale 08e import (static fa-i ity (a9ai ab e fro7 :2SE S*Q 5.0 onwards) e i7i" nates t8e need to prefi; stati- 7e7bers wit8 - ass na7es. It a so e i7inates t8e need to resort to prob e7ati- patterns# i&e definin< -onstants inside an interfa-e. 08e use of t8is feature# 8owe9er# 7ust be restri-ted to tru y - ass independent -onstants. Constants re ated to a parti-u ar - ass# i&e t8ose definin< input or output 9a ues for - ass 7et8ods# s8ou d re7ain asso-iated to t8e - ass t8ey be on< to. In ar<e proDe-ts# t8e import(static feature -an ead to -ode tra-eabi ity prob e7s. Be-ause of t8at# it is i7portant to use it -arefu y# if at a . 3 ample A -o77on (but not re-o77ended) pattern is to put freHuent y used -onstants in an interfa-e# to a9oid e;p i-it y referen-in< t8e - ass t8ey be on< to:
!(@1onstant(interface@(antipattern(:(do(not(use(! public(interface(Space#hysics1onstants(
{ ((((public(static(final(double("5R?T&S#EEH(-(S/////////d(, ((((public(static(final(double(E"E1TRO4&2=SS(-(T.6/TSU6UUe:S6, }( (end(interface public(class(Satellite(implements(Space#hysics1onstants( { ((((public(static(void(main%StringPQ(args*( (((({ ((((((((double(mass(-(..., ((((((((double(energy(-(%"5R?T&S#EEH(V(0*(!(mass, ((((((((... ((((}( (end(main }( (end(class
'0
08is -onfuses t8e - ients of t8e - ass and -reates a on<"ter7 -o77it7ent. If a set of -onstants is rea y so <eneri- and < oba t8at it -annot be asso-iated to any parti-u ar - ass# usin< import(static is a better so ution. 3 ample 08e import(static fa-i ity ets t8e pro<ra77er a9oid Hua ifyin< stati- 7e7" ber na7es wit8out subtypin<. It is ana o<ous in synta; to t8e pa-&a<e import fa-i i" ty# e;-ept t8at it i7ports stati- 7e7bers fro7 a - ass# rat8er t8an - asses fro7 a pa-&a<e:
import(static(esa.Space#hysics1onstants.!, class(Satellite { ((((public(static(void(main%StringPQ(args* (((({ ((((((((double(mass(-(..., ((((((((double(energy(-("5R?T&S#EEH(V(0(!(mass, ((((((((... ((((}( (end(main }( (end(class
+ecommen!ation 41 7se t&pe-safe enumerations as !efine! using the enum ;e&wor!$ Rationale 08e :2SE de9e op7ent -y- e introdu-ed a new feature to :a9a: typesafe enu" 7erations. 0ypesafe enu7erations offer a nu7ber of ad9anta<es wit8 respe-t to t8e pre9ious approa-8 of usin< static(final - ass 9ariab es (so"-a ed int enu7era" tions):
08ey pro9ide -o7pi e"ti7e type safety. 3a ues of an int enu7eration -ou d be assi<ned to 9ariab es intended to -ontain 9a ues of a different enu7eration. 0ype"safe enu7erations pre9ent t8at. 08ey pro9ide a proper na7e spa-e for t8e enu7erated type. Fit8 int enu7er" ations# -onstants 7ust be prefi;ed to a9oid na7e - as8es. 08ey are robust. int enu7erations are -o7pi ed into - ients. C ients 7ust be re-o7pi ed to add# re7o9e# or reorder -onstants.
'1
08ey are infor7ati9e w8en printed. Printin< int enu7eration -onstants disp ays on y t8e nu7eri- 9a ue. Be-ause t8ey are obDe-ts# you -an put t8e7 in -o e-tions. Be-ause t8ey are essentia y - asses# you -an add arbitrary fie ds and 7et8ods.
3 ample
public(enum(#lanet( { ((((2ER1JRO%S.S/Se.0S'(0.+STKeW*' ((((GE4JS%+.UWTe.0+'(W./X6UeW*' ((((E=RT?%X.TKWe.0+'(W.SKU6+eW*' ((((2=RS%W.+06e.0S'(S.STK0eW*' ((((YJ#5TER%6.Te.0K'(((K.6+T0eK*' ((((S=TJR4%X.WUUe.0W'(W./0WUeK*' ((((JR=4JS%U.WUWe.0X'(0.XXXTeK*' ((((4E#TJ4E%6./0+e.0W'(0.+K+WeK*' ((((#"JTO%6.0Ke.00'((6.6SKeW*, ((((private(final(double(mass,((( ((((private(final(double(radius,( (in(<ilograms (in(meters
((((#lanet%final(double(mass'(final(double(radius*( (((({ ((((((((this.mass(-(mass, ((((((((this.radius(-(radius, ((((}( (end(constructor ((((private(double(set2ass%*( (((({ ((((((((return(mass, ((((}( (end(method ((((private(double(setRadius%*( (((({ ((((((((return(radius, ((((}( (end(method }( (end(enum
)."2
Thread SynchroniBation #ssues

+ecommen!ation 4% 7se threa!s onl& where appropriate$ Rationale 08reads are not a @si 9er bu etA for i7pro9in< app i-ation perfor7an-e. *epend" in< on a 9ariety of fa-tors# t8e o9er8ead reHuired to swit-8 between t8reads 7ay in" deed 7a&e an app i-ation s ower. Before introdu-in< t8reads into an app i-ation# try to deter7ine w8et8er it -an rea y benefit fro7 t8eir use. Consider usin< t8reads if your app i-ation needs:
0o rea-t to 7any e9ents si7u taneous y (i.e.# an Internet ser9er).
'2
0o pro9ide a 8i<8 e9e of responsi9eness (i.e.# an intera-ti9e app i-ation t8at -ontinues to respond to user a-tions e9en w8en perfor7in< ot8er -o7putations). 0o ta&e ad9anta<e of 7a-8ines wit8 7u tip e pro-essors.
+ecommen!ation 43 +e!uce s&nchroniCation to the minimum possi1le$ Rationale Syn-8roniEation is e;pensi9e. A-Huirin< and re easin< t8e spe-ia obDe-ts ne-" essary to syn-8roniEe a se-tion of -ode is often a -ost y operation. $oreo9er# syn" -8roniEation seria iEes a--ess to an obDe-t# redu-in< -on-urren-y. *o not arbitrari y syn-8roniEe e9ery pub i- 7et8od. Before syn-8roniEin< a 7et8od# -onsider w8et8er it a--esses s8ared and non"syn-8roniEed states. If it does not# if t8e 7et8od on y operates on its o-a 9ariab es# para7eters# or syn-8roniEed obDe-ts# syn-8roniEation is probab y not reHuired. Additiona y# do not syn-8roniEe - asses t8at pro9ide funda7enta data types or stru-tures. +ecommen!ation 44 6o not s&nchroniCe an entire metho! if the metho! contains significant operations that !o not nee! s&nchroniCation$ Rationale A 7et8od annotated wit8 t8e synchroni$ed &eyword a-Huires a o-& on t8e asso-iated obDe-t at t8e be<innin< of t8e 7et8od and 8o ds t8at o-& unti t8e end of t8e 7et8od. As is often t8e -ase# 8owe9er# on y a few operations wit8in a 7et8od 7ay reHuire syn-8roniEation. In su-8 a situation# 7et8od e9e syn-8roniEation -an be 7u-8 too -oarse. 08e a ternati9e to 7et8od e9e syn-8roniEation is to use t8e syn-8roniEed b o-& state7ent:
protected(void(processReDuest(%*( { ((((ReDuest(reDuest(-(get4extReDuest%*, ((((ReDuest5d(id(-(reDuest.get5d%*, ((((synchroni$ed(%this*( (((({ ((((((((ReDuest?andler(handler(-(this.handler2ap.get%id*, ((((}( (end(method ((((handler.handle%reDuest*, }( (end(method
08ou<8 t8is does not pertain to safety -riti-a :a9a (see -8apter =)# it does see7 to -ontradi-t t8e no syn-8roniEed b o-& ru e in safety -riti-a :a9a. As an a ter" nati9e# one -ou d pro9ide a syn-8roniEed pri9ate 7et8od -a ed by t8e pub i- or pro" te-ted 7et8od to redu-e t8e e;tent of t8e syn-8roniEation. Su-8 a 7et8od -ou d a so be used by ot8er pub i- 7et8ods as we .
protected(void(processReDuest%* { ReDuest(reDuest(-(get4extReDuest%*,
ReDuest5d(id(-(reDuest.get5d%*, ReDuest?andler(handler(-(get?andler%id*, handler.handle%reDuest*, }( (end(method
'(
private(synchroni$ed(ReDuest?andler(get?andler%ReDuest5d(id* { return(this.handler2ap.get%id*, }( (end(method
%ote t8at t8e e;a7p e as <i9en wi not wor&# sin-e t8e 8and er 9ariab e is de" fined wit8in t8e syn-8roniEation b o-& but is referen-ed after t8e end of t8e b o-&.
+ecommen!ation 4# 8)oi! unnecessar& s&nchroniCation when rea!ing or writing instance )aria1les$ Rationale 08e :a9a pro<ra77in< an<ua<e <uarantees t8at read and write operations are ato7i- for obDe-t referen-es as we as for a pri7iti9e types# wit8 t8e e;-eption of long and double. 08erefore# it is possib e to a9oid t8e use of syn-8roniEation w8en readin< or writin< ato7i- data. .n t8e ot8er 8and# if t8e 9a ue of an ato7i- 9ariab e depends on# or is re ated to# t8ose of ot8er 9ariab es# syn-8roniEation 7ay sti be ne-essary. 3 ample In t8e fo owin< e;a7p e# t8e assi<n7ents of x and y 7ust be syn-8roniEed to" <et8er be-ause t8ey are interdependent 9a ues:
public(void(synchroni$ed(set1enter%int(x'(int(y*( { ((((this.x(-(x, ((((this.y(-(y, }( (end(method
08e fo owin< e;a7p e does not reHuire syn-8roniEation be-ause it uses an ato7i- assi<n7ent of an obDe-t referen-e:
public(void(set1enter(%#oint(p*( { ((((this.point(-(%#oint*(p.clone%*(, }( (end(method
P ease note# t8at t8e e;a7p e <i9en trades off ess syn-8roniEation for 7ore <arba<e -o e-tion o9er8ead. 1owe9er# if Point is i77utab e# t8en clone is not ne-" essary.
BSSC 2005(2) Issue 1.0 C1AP0E) > :A3A *ESI5% A%* P).5)A$$I%5 5/I*E2I%ES +ecommen!ation 42 7se s&nchroniCe! wrappers to pro)i!e s&nchroniCe! interfaces$
'4
/se syn-8roniEed wrappers to pro9ide syn-8roniEed 9ersions of - asses in situ" ations w8ere t8ey are needed# i.e. to prote-t t8e inte<rity of s8ared data and to -o7" 7uni-ate pro<ra7 state -8an<es effi-ient y between -ooperatin< t8reads. Syn-8ro" niEed wrappers pro9ide t8e sa7e interfa-e as t8e ori<ina - ass# but t8eir 7et8ods are syn-8roniEed. A stati- 7et8od of t8e wrapped - ass pro9ides a--ess to t8e syn" -8roniEed wrapper. Rationale Syn-8roniEed wrappers a ow for t8e sa7e -ode to be used in an unsyn-8ro" niEed and in a syn-8roniEed fas8ion in t8e sa7e pro-ess. 3 ample 08e fo owin< e;a7p e (not 7eant to be run or be a fu - ass definition but on y to s8ow t8e prin-ip e) de7onstrates a sta-&# w8i-8 8as a defau t# non"syn-8roniEed interfa-e and a syn-8roniEed interfa-e pro9ided by t8e wrapper - ass.
public(class(Stac<( { ((((public(void(push(%Object(o*( (((({ ((((((((... ((((}( (end(method ((((public(Object(pop%*( (((({ ((((((((... ((((} (end(method ((((public(static(Stac<(createSynchroni$edStac<%*( (((({ ((((((((return(new(Synchroni$edStac<%*, ((((}( (end(method }( (end(class class(Synchroni$edStac<(extends(Stac<( { ((((public(synchroni$ed(void(push(%Object(o*( (((({ ((((((((super.push%o*, ((((}( (end(method ((((public(synchroni$ed(Object(pop%*( (((({ ((((((((return(super.pop%*, ((((}( (end(method }( (end(class
P ease note t8at 8a9in< a fa-tory 7et8od for a sub- ass -reates a -ir-u ar dependen-y. 08is wi often not be possib e wit8out 7odifyin< -ode fro7
BSSC 2005(2) Issue 1.0 C1AP0E) > :A3A *ESI5% A%* P).5)A$$I%5 5/I*E2I%ES ot8er sour-es ( ibraries). If one does 8a9e -ontro o9er t8e ori<ina - ass and one wants a fa-tory 7et8od# it 7ay be better to use an inner - ass for t8e syn-8roniEed 9ersion. +ecommen!ation 4> Consi!er using notify)* instea! of notifyAll)*$
'5
08e notify%* and notify=ll%* 7et8ods are used w8en a t8read 7ust b o-& waitin< for ot8er t8reads to perfor7 a parti-u ar operation. F8ene9er possib e# use t8e 7ore effi-ient notify%* 7et8od instead of its notify=ll%* -ounterpart. /se notify%* w8en t8reads are waitin< on a sin< e -ondition and w8en on y a sin< e waitin< t8read 7ay pro-eed at a ti7e. /se notify=ll%* w8en t8reads 7ay wait on 7ore t8an one -ondition or if it is possib e for 7ore t8an one t8read to pro-eed in response to a si<na . Rationale 08e notify%* 7et8od is 7ore effi-ient. +ecommen!ation 40 7se the !ou1le-chec; pattern for s&nchroniCe! initialiCation$ /se t8e doub e"-8e-& pattern in situations w8ere syn-8roniEation is reHuired durin< initia iEation# but not after it. Rationale 08e doub e"-8e-& pattern 7a&es it possib e to a9oid e;pensi9e syn-8roniEation operations in 7any -o77on situations. 3 ample 08is -ode a so prote-ts a<ainst si7u taneous initia iEation but it uses t8e dou" b e"-8e-& pattern to a9oid syn-8roniEation e;-ept durin< initia iEation:
"og(get"og%*( { ((((if(%this.log(--(null*( (((({ ((((((((synchroni$ed(%this*( (((((((({ ((((((((((((if(%this.log(--(null*( (((((((((((({ ((((((((((((((((this.log(-(new("og%*, ((((((((((((}( (end(if ((((((((}( (end(method ((((}( (end(if ((((return(this.log, }( (end(method
BSSC 2005(2) Issue 1.0 C1AP0E) ' ).B/S0%ESS
'>
Chapter $ Robustness
$." #ntroduction
08e -on-ept of robustness app ies to software de9e op7ent at different e9e s. A runnin< software syste7 is -onsidered robust if it rea-ts proper y to une;pe-ted situations. A pie-e of -ode is -onsidered robust w8en it is instru7ented in su-8 a way t8at it 8e ps dete-t and -orre-t errors (bot8 in pro<ra77in< and durin< e;e-u" tion). 08is -8apter is -on-erned wit8 robustness in :a9a syste7s. So7e of t8e ru es and re-o77endations are dire-ted to a-8ie9in< 7ore robust -ode (-on-rete y# t8e se-tions on desi<n by -ontra-t and assertions). .t8ers# parti-u ar y t8ose re ated to error 8and in<# are 7ore -on-erned wit8 run"ti7e robustness. 08e o9era app i-ation of t8e ru es and re-o77endations in t8is -8apter s8ou d ead to 7ore re iab e sys" te7s.
$.%
Design by Contract
+ecommen!ation 4? 6efine metho! contracts an! enforce them$ *efine a @-ontra-tA for ea-8 7et8od you write# -onsistin< of its pre" and post" -onditions:
08e pre-onditions are t8e set of o<i-a -onditions on t8e obDe-t state and pa" ra7eter 9a ues t8at 7ust 8o d in order for t8e 7et8od to be ab e to perfor7 its tas&. 08e post-onditions are t8e set of o<i-a -onditions on t8e obDe-t state and 7et8od return 9a ue t8at 7ust 8o d after t8e 7et8od 8as perfor7ed its tas&.
Pre-onditions are t8e part of t8e -ontra-t a 7et8od -a er 7ust -o7p y wit8. Post-onditions are t8e part of t8e -ontra-t a 7et8od i7p e7entation 7ust fu fi . F8ene9er possib e# a pro<ra7 s8ou d use assertions or ot8er adeHuate 7eans to e;p i-it y -8e-& for 7et8od -ontra-ts bein< respe-ted. /nfortunate y# t8ou<8# so7e o<i-a pre" or post-onditions of a 7et8od -ou d be te-8ni-a y 9ery diffi-u t or onerous to -8e-&. *o your best# 8owe9er# to a ways -8e-& as 7u-8 as te-8ni-a y feasib e. Rationale 08e usa<e of -ontra-ts is a we &nown way to 7a&e 7odu es 7ore robust and re iab e.
''
+ecommen!ation #0 =hene)er possi1le, a metho! shoul! either return the result specifie! 1& its contract, or throw an exception when that is not possi1le$ Rationale 08e idea be8a9ior for a 7et8od is to return nor7a y on y w8en its -ontra-t was -o7p ete y fu fi ed. If t8is is not t8e -ase# t8e 7et8od s8ou d ter7inate abnor7a y wit8 an e;-eption. 08is -an be a-8ie9ed by proper y -8e-&in< t8e pre" and post-on" ditions of a 7et8od usin< an adeHuate -o7bination of nor7a -onditions and asser" tions. )u e >': Preser9e 7et8od -ontra-ts in deri9ed - asses. $et8ods t8at o9erride 7et8ods in a base - ass 7ust preser9e t8e pre" and post-onditions spe-ified in t8e base - ass. $ore -on-rete y:
A sub- ass 7et8od is not a owed to stren<t8en t8e pre-onditions of its -ounter" part in a super- ass. A sub- ass 7et8od is not a owed to wea&en t8e post-onditions of its -ounter" part in a super- ass.
Rationale .n y by respe-tin< t8is ru e is it possib e to <uarantee t8at instan-es of a super" - ass -an be safe y and transparent y substituted by instan-es of one of its sub- ass" es. Su-8 substitutabi ity is a &ey prin-ip e of obDe-t"oriented desi<n.
$.*
5ssertions
+ecommen!ation #1 +el& on <a)aEs assert statement to explicitl& chec; for programming errors in &our co!e$ /se :a9aMs assert state7ent ibera y to ensure t8at t8e basi- pre7ises upon w8i-8 a pie-e of -ode was desi<ned and bui t a-tua y 8o d durin< runti7e. Rationale Assertions are a si7p e# yet 9ery 9a uab e 7e-8anis7 t8at -an <reat y 8e p to dia<nose prob e7s durin< testin< and e9en after dep oy7ent. Additiona y# sin-e as" sertions -an be easi y disab ed# t8eir i7pa-t on perfor7an-e in a produ-tion en9iron" 7ent is usua y ne< i<ib e. )u e >!: E;p i-it y -8e-& 7et8od para7eters for 9a idity# and t8row an adeHuate e;" -eption in -ase t8ey are not 9a id. *o not use t8e assert state7ent for t8is pur" pose. Rationale It is a -o77on pro<ra77in< error to in9o&e a 7et8od wit8 in9a id para7eter 9a ues# i.e.# para7eter 9a ues t8at do not ie wit8in t8e 9a ue ran<es e;pe-ted by t8e 7et8od. 08e a--epted pra-ti-e in t8e :a9a pro<ra77in< -o77unity is to -8e-& for para7eter 9a idity usin< standard -ode (as opposite to assertions) in order to &eep su-8 -8e-&s per7anent y enab ed durin< pro<ra7 e;e-ution# re<ard ess of w8et8er
BSSC 2005(2) Issue 1.0 C1AP0E) ' ).B/S0%ESS assertions are enab ed or not.
'!
C8e-&in< for para7eter 9a idity and# <enera y# for 7et8od pre-onditions# 8e ps to <uarantee t8at estab is8ed interfa-es in a syste7 are bein< used as spe-ified. 08is# in turn# 8e ps to redu-e t8e -oup in< in a syste7# by 7a&in< it possib e to re" p a-e 7odu e or -o7ponent i7p e7entations w8en ne-essary. )u e >=: Add dia<nosti- -ode to a areas t8at# a--ordin< to t8e e;pe-tations of t8e pro<ra77er# s8ou d ne9er be rea-8ed. Areas of a pro<ra7 t8at are not e;pe-ted to e9er be rea-8ed by t8e f ow of -on" tro (for e;a7p e# default -ases for switch state7ents# w8en it is &nown t8at t8e case se-tions -o9er a possib e situations) s8ou d sti -ontain -ode to produ-e a di" a<nosti- 7essa<e if t8ey are rea-8ed due to a pro<ra77in< error. Rationale Addin< su-8 dia<nosti- -ode 7a&es it easier to dete-t and -orre-t a nu7ber of potentia software defe-ts. 08is is an effe-ti9e for7 of defensi9e pro<ra77in<. )u e '0: *o not use e;pressions wit8 side effe-ts as ar<u7ents to t8e assert state7ent. Rationale Besides produ-in< a resu t 9a ue# e;pressions wit8 side effe-ts potentia y 7odi" fy 9ariab e 9a ues (t8in& of an e;pression in9o&in< a 7et8od t8at not on y returns a 9a ue but 7odifies t8e obDe-t). If an e;pression wit8 a side effe-t is used as ar<u" 7ent for an assert state7ent# t8e be8a9ior of t8e pro<ra7 wi probab y -8an<e w8en assertions are disab ed. Sin-e it s8ou d a ways be possib e to disab e asser" tions for a pro<ra7 or subsyste7# t8ey are not a owed to 8a9e side effe-ts.
$.,
Debugging
)u e '1: /se t8e :a9a o<<in< 7e-8anis7 for a debu<<in< state7ents instead of resortin< to t8e System.out.println fun-tion. Rationale 08e syste7 strea7s (e.<. in# out# err* s8ou d on y be used by -o77and ine app i-ations. Additiona y# usin< t8e o<<in< 7e-8anis7 7a&es it possib e to &eep a debu<<in< state7ents in t8e -ode# and to use t8e7 at t8e finest <ranu arity durin< troub e s8ootin<. *urin< nor7a operation of t8e software# on t8e ot8er 8and# o<<in< -an be set to T-oarseT and# as su-8# wi not pro-ess any debu< 7essa<es. It a so sa9es wor& in tryin< to find t8e sour-e of stray System.out.println state7ents eft in t8e -ode after debu<<in<.
$./
3 ceptions and 3rror :andling

E;-eptions are t8e 7ain te-8niHue t8e :a9a pro<ra77in< an<ua<e offers to 8and e errors and abnor7a -onditions. 08ey 8a9e a nu7ber of ad9anta<es o9er 7ore traditiona error 7ana<e7ent te-8niHues:
08ey - ean y separate error 8and in< -ode fro7 ot8er -ode.
'=
08ey auto7ati-a y propa<ate errors up t8e -a sta-& in a fas8ion t8at is -o7" patib e wit8 t8e <enera pro<ra7 -ontro stru-ture. 08ey a ow <roupin< of error types# a owin< for 7ore f e;ib e and stru-tured er" ror 8and in<.
08e ru es and re-o77endations in t8is se-tion are re ated to t8e appropriate use of e;-eptions in :a9a pro<ra7s. )u e '2: /se un-8e-&ed# run"ti7e e;-eptions to 8and e serious une;pe-ted abnor" 7a situations# in- udin< t8ose t8at 7ay indi-ate errors in t8e pro<ra7Gs o<i-. /se un-8e-&ed e;-eptions (i.e.# e;-eption obDe-ts deri9ed dire-t y or indire-t y fro7 eit8er t8e java.lang.Error or t8e java.lang.RuntimeException(- ass) to 8and e situations typi-a y arisin< fro7 pro<ra77in< errors# or fro7 abnor7a situ" ations of su-8 a se9ere nature t8at pro<ra7 ter7ination is i77inent. Rationale 08e situations des-ribed by t8is ru e are su-8 t8at t8ere is not 7u-8 an app i-a" tion -an do to 8and e t8e7 proper y. So 9in< su-8 situations usua y reHuires e;terna inter9ention (for e;a7p e# to fi; a -ode defe-t). ConseHuent y# it is not wort8w8i e to 7a&e t8e pro<ra7 o<i- 7ore -o7p e; be-ause of t8e7# w8i-8 wou d be t8e -ase if -8e-&ed e;-eptions were used. /n-8e-&ed e;-eptions -an sti be trapped if t8e pro<ra7 8as a reasonab e way of 8and in< t8e7. 3 ample /n-8e-&ed e;-eptions -ou d be used to 8and e situations su-8 as:
A fai ed assertion (t8e assert statement auto7ati-a y t8rows an e;-eption). An out"of"bounds inde;. A di9ision by Eero. An atte7pt to dereferen-e a nu referen-e. A serious input6output error. An operatin< syste7 fai ure.
)u e '(: /se -8e-&ed e;-eptions to report errors t8at 7ay o--ur# e9en if rare y# un" der nor7a pro<ra7 operation. /se -8e-&ed e;-eptions to 8and e prob e7ati- situations t8at 7ay o--ur durin< nor7a pro<ra7 operation. In 7any -ases# su-8 prob e7s -an be 8and ed appropri" ate y by t8e -a er of t8e 7et8od t8rowin< t8e e;-eption. Rationale Errors t8at 7ay o--ur under durin< nor7a pro<ra7 operation 7ust be reported t8rou<8 -8e-&ed e;-eption in order to 7a&e t8e -a er aware of t8e fa-t t8at t8ey s8ou d be 8and ed in so7e way or anot8er.
BSSC 2005(2) Issue 1.0 C1AP0E) ' ).B/S0%ESS 3 ample C8e-&ed e;-eption -ou d be used to 8and e situations su-8 as:
!0
08e user typed in9a id infor7ation. In-orre-t y for7atted infor7ation was read fro7 an open networ& -onne-tion. A - ient does not 8a9e t8e reHuired se-urity pri9i e<es.
)u e '4: *o not si ent y absorb a run"ti7e or error e;-eption. Rationale Brea&in< t8is ru e 7a&es -ode 8ard to debu< be-ause 9a uab e infor7ation <ets ost. E9en if you 8a9e -oded a catch b o-& si7p y to -at-8 an e;-eption you do not e;pe-t to o--ur# print at east a sta-& tra-e. Vou ne9er &now w8en so7et8in< @i7" possib eA 7i<8t o--ur wit8in your software. 3 ample
try( { ((((for(%int(i(-(v.si$e%*(:(6,(i(M-(/,(i::* (((({ ((((((((ostream.println%v.element=t%i**, ((((}( (end(for }( (end(try catch(%=rray5ndexOutOf3oundsException(e*( { (((( (Should(never(get(here(but(if(we(do'(nobody(will(ever(<now. (((( (#rint(a(stac<(trace(just(in(case. ((((e.printStac<Trace%*, }( (end(catch
+ecommen!ation #% =hene)er possi1le, use finally 1loc;s to release resources$ Rationale .n-e a try b o-& is entered# t8e -orrespondin< finally b o-& is <uaranteed to be e;e-uted# re<ard ess of w8et8er an e;-eption is t8rown or not. 08is 7a&es t8e finally b o-& an idea p a-e to re ease any resour-es a-Huired prior to enterin< or wit8in t8e try b o-&. +ecommen!ation #3 'nl& con)ert exceptions to a!! information$ It is often ne-essary to trap an e;-eption on y to re"t8row it ri<8t away (for e;" a7p e# be-ause anot8er type of e;-eption is now reHuired). F8i e doin< so# do not dis-ard any infor7ation# but add any new infor7ation you 7ay 8a9e to t8e e;istin< e;-eption. Rationale *is-ardin< infor7ation 7ay 7a&e so7e prob e7s e;tre7e y diffi-u t to dia<" nose. In -ertain -ases# it 7ay ead to prob e7s <oin< undete-ted t8at wou d 8a9e
BSSC 2005(2) Issue 1.0 C1AP0E) ' ).B/S0%ESS ot8erwise been noti-ed. )u e '5: %e9er i<nore error 9a ues reported by 7et8ods.
!1
A t8ou<8 t8e typi-a :a9a pra-ti-e is to re y on e;-eptions for 8and in< error -onditions# so7e ibraries sti use spe-ia return 9a ues to indi-ate abnor7a -ondi" tions. In su-8 -ases# a ways -8e-& for error 9a ues and -ode an appropriate re" sponse. A possib e -ourse of a-tion is to wrap su-8 7et8ods into 7et8ods t8at -8e-& for error return 9a ues and t8row appropriate e;-eptions w8en t8ey appear. Rationale I<norin< error 7essa<es 7ay diffi-u t t8e dete-tion of -ertain prob e7s.
$.)
Type Safety
+ecommen!ation #4 Encapsulate enumerations as classes$ En-apsu ate enu7erations as - asses to pro9ide type"safe -o7parisons of enu" 7erator 9a ues. 08e enum -onstru-t# a9ai ab e in :2SE 5.0 and ater# is a 9ery -on9e" nient way of doin< so. Rationale A proper en-apsu ated enu7eration is type"safe# w8i-8 7eans t8at t8e -o7pi er is ab e to dete-t i7proper uses of t8e enu7eration -onstants.
BSSC 2005(2) Issue 1.0 C1AP0E) ! P.)0ABI2I0V
!2
Chapter + !ortability
+." #ntroduction
08e :a9a p atfor7 is one of t8e few software te-8no o<ies a owin< bot8 sour-e and byte -ode to be 7ade 100W p atfor7"independent wit8 re ati9e y itt e effort. It 7eans writin< and -o7pi in< -ode on-e and runnin< it e9eryw8ere wit8out 7odifi-a" tion (under t8e -ondition# of -ourse# t8at a suitab e :a9a 3irtua $a-8ine is insta ed on ea-8 tar<et p atfor7). 08e resu t is -o7p ete independen-e of operatin< syste7 and 8ardware type. 08e ru es and re-o77endations in t8is -8apter are intended to support pro<ra77ers in produ-in< 100W portab e :a9a -ode. It is i7portant to point out# t8at so7e parti-u ar app i-ations -annot be (and probab y do not need to be) 100W portab e. Code written for rea "ti7e :a9a 9irtua 7a-8ines is one e;a7p e. App i-ations t8at dire-t y a--ess 8ardware are anot8er. E9en in su-8 -ases# 8owe9er# t8e ru es and re-o77endations presented 8ere -ou d be 8e pfu # sin-e a-8ie9in< a 7a;i7u7 of portabi ity is a ways 9a uab e.
+.%
Rules
+ecommen!ation ## =hene)er possi1le, prefer the Swing 8PI to the ol! 8=5 8PI for !e)eloping graphical user interfaces$ Rationale 08e Swing - asses are desi<ned for 100W portabi ity# and support a tunab e oo&"and"fee (Findows" i&e# /ni;" i&e# $otif" i&e# 2inu;" i&e# et-). 08ey s8ou d be used in preferen-e to t8e o der AF0 API. 08e AF0 API wi sti run on 9arious p at" for7s# but wi rea-t or oo& different y dependin< on t8e under yin< operatin< sys" te7. )u e '>: *o not re y on t8read s-8edu in< parti-u arities to define t8e be8a9ior of your pro<ra7# use syn-8roniEation instead. Rationale 08e way an operatin< syste7 or its under yin< 8ardware distribute pro-essor -y- es a7on< t8reads# -an 9ary wide y fro7 p atfor7 to p atfor7. A pro<ra7 t8at e;" pe-ts t8e t8read syste7 to# for e;a7p e# 8and e -ontro fro7 one t8read to t8e ne;t at a parti-u ar point in t8e e;e-ution# 7ay wor& on so7e p atfor7s but not on ot8ers. .ne i7p i-ation of t8is fa-t is t8at no a7ount of testin< is enou<8 to <uarantee t8at a t8read"based a <orit87 is a-tua y -orre-t in a p atfor7 independent fas8ion. Carefu inspe-tion# or e9en for7a 9erifi-ation are a ways ne-essary. /nfortunate y# t8is is a prob e7 t8at is neit8er easy to dete-t nor to -orre-t. *e"
!(
si<nin< -orre-t t8read"safe a <orit87s reHuires app yin< proper prin-ip es and 9a i" datin< t8e7 t8orou<8 y. 3 ample Be-ause of t8e a-& of syn-8roniEation between t8reads# t8e pro<ra7 be ow -ou d write @6A or @0A# or e9en produ-e an error dependin< on t8e -8ara-teristi-s of t8e under yin< t8read i7p e7entation. 08is -ou d not be noti-ed by -asua testin<. If t8e t8read i7p e7entation# for e;a7p e# <uarantees t8at t8e assi<n7ent in 7et8od @runA is ato7i-# it wou d -onsistent y print @2A.
class(1ounter(implements(Runnable( { ((((static(int(counterGalue(-(/, ((((public(void(run%*( (((({ ((((((((counterGalue(.-(6, ((((}( (end(method ((((public(static(void(main%StringPQ(args* (((({ ((((((((try( (((((((({ ((((((((((((Thread(thread6(-(new(Thread%new(1ounter%**, ((((((((((((thread6.set#riority%6*, ((((((((((((Thread(thread0(-(new(Thread%new(1ounter%**, ((((((((((((thread0.set#riority%0*, ((((((((((((thread6.start%*, ((((((((((((thread0.start%*, ((((((((((((thread6.join%*, ((((((((((((thread0.join%*, ((((((((((((System.out.println%counterGalue*, ((((((((}( (end(try catch(%Exception(e*( (((((((({ ((((((((((((e.printStac<Trace%*, ((((((((}( (end(catch ((((}( (end(main }( (end(class
)u e '': A9oid nati9e 7et8ods. Rationale %ati9e 7et8ods (i.e.# 7et8ods written in C?? or ot8er pro<ra77in< an<ua<es and in&ed to t8e :a9a 9irtua 7a-8ine t8rou<8 t8e <a)a Fati)e Betho! Interface) are usua y tied to t8e p atfor7 t8ey w8ere de9e oped in. Portin< t8e7 to ot8er p atfor7s 7ay be a bi< -8a en<e# in9o 9in< 7u ti"p atfor7 -o7pi ation syste7s# and -onditiona -ode.
BSSC 2005(2) Issue 1.0 C1AP0E) ! P.)0ABI2I0V +ecommen!ation #2 6o not use the java.lang.Runtime.exec metho!$ Rationale
!4
08e java.lang.Runtime.exec 7et8od starts arbitrary pro<ra7s in t8e sa7e -o7puter syste7 w8ere t8e -a er pro<ra7 is runnin<# referen-in< t8e7 by na7e. Sin-e t8e na7in< ru es for pro<ra7s differ wide y a7on< -o7putin< p atfor7s# use of java.lang.Runtime.exec -an ne9er be 7ade tota y portab e. %ote: 08is is Huite a 8ard restri-tion. It is suffi-ient to a9oid 8ard -odin< pro<ra7 na7es and to use a -onfi<uration fi e instead.
+ecommen!ation #> 6o not har!-co!e !ispla& attri1utes, li;e position an! siCe for graphical element, text font t&pes an! siCes, colors, la&out management !etails, etc$ Rationale It -an be 9ery diffi-u t# if not i7possib e# to find a fi;ed set of disp ay 9a ues t8at 7a&es an app i-ation run proper y in e9ery sin< e syste7. A Dudi-ious use of t8e sys" te7 properties# to<et8er wit8 proper app i-ation of re e9ant <rap8i-a too &it fa-i ities (for e;a7p e# ayout 7ana<ers) s8ou d a9oid 7ost portabi ity prob e7s re ated to dis" p ay attributes. +ecommen!ation #0 Chec; all uses of the <a)a reflection features for in!irect in)ocation of metho!s that ma& cause porta1ilit& pro1lems$ Rationale 08e ref e-tion features a9ai ab e in t8e :a9a pro<ra77in< an<ua<e a ow indi" re-t y instantiatin< arbitrary - asses and in9o&in< arbitrary 7et8ods. F8i e doin< t8is# a pro<ra7 7ay in9o&e 7et8ods t8at are not portab e# or in9o&e portab e 7et8ods in non"portab e ways. Code usin< ref e-tion 7ust be -arefu y inspe-ted for su-8 prob" e7s if portabi ity is a priority. )u e '!: )estri-t t8e use of t8e System.exit 7et8od to t8e -ases des-ribed be" ow. 08e System.exit 7et8od ter7inates a pro<ra7 instant y. )estri-t its use to:
,ata errors t8at abso ute y reHuire ter7inatin< t8e app i-ation i77ediate y. /ti ity pro<ra7s intended to be in9o&ed fro7 t8e -o77and ine or fro7 s-ript in" terpreters# w8ere t8e pro<ra7 return 9a ue 7ay be i7portant.
Rationale Sudden ter7ination of a pro<ra7 7ay ead to undesired intera-tions wit8 t8e user or wit8 t8e operatin< syste7 (i.e.# a pro<ra7 sudden y - osin< a of its windows or ter7inatin< wit8out re easin< a resour-es). Su-8 be8a9iors 7ay be a--eptab e in so7e p atfor7s and una--eptab e in ot8ers.
BSSC 2005(2) Issue 1.0 C1AP0E) ! P.)0ABI2I0V )u e '=: *o not 8ard"-ode fi e na7es and pat8s in your pro<ra7. Rationale
!5
,i e na7in< ru es and ru es to for7 fi e pat8s 9ary wide y dependin< on t8e op" eratin< syste7. 1ard -oded na7es -an be interpreted Huite different y w8en a pro" <ra7 is 7o9ed to a different p atfor7. Fit8 -arefu pro<ra77in<# it is possib e for a pro<ra7 to parse or bui d fi e pat8s portab y by usin< t8e fie ds and 7et8ods in t8e java.io.Aile - ass. 1owe9er# doin< t8is s8ou d be eft as a ast resort. Pro<ra7s s8ou d re y# as 7u-8 as possib e# on ot8er fa-i ities offered by t8e :a9a p atfor7# i&e property fi es or fi e se e-tion dia o< bo;es. 3 ample So7e fi e na7in< -on9ention differen-es between t8e /%I+ and *.S6Findows p atfor7s:
In /%I+ t8e -8ara-ter separator is t8e s as8 (@ A)# w8ereas in *.S6Findows it is t8e ba-&"s as8 (@EA). *.S6Findows uses dri9e etters (i.e. @c;EwindowsA) w8i e /%I+ does not. Spa-es are -o77on y used as part of Findows fi e na7es. 08ey are unusua in /%I+ and 7ay -ause prob e7s in so7e syste7s. 08e period (@.A) is a spe-ia -8ara-ter in *.S6Findows# separatin< t8e fi e na7e fro7 its t8ree" etter e;tension. In /%I+# periods are not spe-ia and -an be (and often wi be) used twi-e in a sin< e na7e. *.S6Findows i<nores -ase differen-es# w8ereas /%I+ does not. In9o&in< t8e java.io.Aile5nputStream wit8 t8e strin< @RE=H2E.T>TA wi wor& under Findows to open a fi e -a ed @Readme.txtA. In /%I+ it wi fai .
+ule 00 8lwa&s ma;e <6BC !ri)er names configura1le, !o not har! co!e them$ Rationale :*BC dri9ers# parti-u ar y t8ose in- udin< nati9e -ode# -an be ess portab e t8an t8e :a9a pro<ra7 usin< t8e7. $a&in< t8e spe-ifi- dri9er na7e -onfi<urab e t8rou<8 t8e standard jdbc.drivers syste7 property# a property fi e# or so7e ot8er# -usto7 7e-8anis7# <uarantees t8at a pro<ra7 -an be re-onfi<ured to use a different dri9er if t8at 8appens to be ne-essary w8en 7o9in< it to a new p atfor7. )u e !1: *o not re y on a parti-u ar -on9ention for ine ter7ination. Rationale 08e way te;t is represented in fi es is different for e9ery sin< e p atfor7. E9en on p atfor7s usin< t8e ASCII -8ara-ter set# ine ends are represented usin< a 9ariety of -8ara-ters and -8ara-ter -o7binations. Fritin< -ode t8at re ies on a parti-u ar -8ara-ter or -8ara-ter seHuen-e to ter7inate ines wi ead to portabi ity prob e7s /se t8e readLine 7et8od fro7 t8e java.io.3ufferedReader - ass to fet-8 -o7p ete ines of te;t# and t8e write"ine or println fun-tions to output ines of te;t. 08ese 7et8ods wor& re iab y wit8 any o-a -on9entions t8e p atfor7 7ay 8a9e. *ependin< on t8e prob e7 at 8and# ot8er - asses and 7et8ods in t8e
BSSC 2005(2) Issue 1.0 C1AP0E) ! P.)0ABI2I0V :a9a ibrary 7ay be ab e to 8and e te;t fi es in a portab e way. )u e !2: )estri-t t8e use of System.in# System.out or System.err to pro" <ra7s e;p i-it y intended for t8e -o77and ine. Rationale
!>
%ot a syste7 p atfor7s supported by t8e :a9a pro<ra77in< an<ua<e 8a9e nati9e standard input# output# and error strea7s# and e9en t8ose t8at do# 7ay run pro<ra7s under -onditions w8ere so7e or a of t8ose strea7s are not a--essib e (i.e. ser9er pro<ra7s under /%I+). /sin< a 5/I or# a ternati9e y# writin< to and read" in< fro7 nor7a fi es 7ay so 9e t8e prob e7 in 7any -ases. +ecommen!ation #? +el& on the wi!el& ;nown P'SI4 con)entions to !efine the s&ntax of &our comman! line options$ /se t8e we &nown P.SI+ synta; (option na7es pre-eded wit8 a das8 @"A -8ar" a-ter) for options. F8ene9er possib e# pro9ide a ternati9es to t8e -o77and ine# i&e a <rap8i-a interfa-e or -onfi<uration fi es. Rationale Co77and ine option parsin< is done -o7p ete y by :a9a app i-ations. /nfortu" nate y# t8e usua synta; for -o77and ine options -an 9ary wide y fro7 p atfor7 to p atfor7. )u e !(: F8en ne-essary# use t8e internationa iEation and o-a iEation features of t8e :a9a p atfor7. If your pro<ra7 -ontains user 9isib e te;ts# or any ot8er for7 of data disp ay or entry t8at 7ay 9ary dependin< on o-a -on9entions# use t8e internationa iEation and o-a iEation features of t8e :a9a p atfor7 to 7a&e your wor& easi y adaptab e to t8e o-a -on9entions of any potentia users. Rationale 08e :a9a internationa iEation and o-a iEation features are robust# we do-u" 7ented and p atfor7"independent. +ecommen!ation 20 +estrict the use of non 8SCII characters in &our messages to the minimum possi1le$ Rationale So7e p atfor7s -annot disp ay arbitrary 7nico!e -8ara-ters. .n t8e ot8er 8and# usin< non ASCII -8ara-ters in internationa iEation resour-es is sti appropriate# sin-e internationa iEation -an a ways be turned off. )estri-tin< your ori<ina 7essa<es to ASCII <uarantees t8at your pro<ra7 wor&s (e9en if wit8 so7ew8at restri-ted fun-" tiona ity) in any p atfor7.
BSSC 2005(2) Issue 1.0 C1AP0E) ! P.)0ABI2I0V )u e !4: *o not 8ard -ode position and siEes of <rap8i-a e e7ents. Rationale
!'
Appropriate siEes for for <rap8i-a e e7ents -an on y be -a -u ated dependin< on t8e -urrent s-reen siEe and reso ution# se e-ted font siEe# and ot8er fa-tors t8at depend on t8e parti-u ar 8ardware and software p atfor7# as we as on t8e user"se" e-ted options. /sin< a ayout 7ana<er not on y abstra-ts t8is detai s in a portab e way# but often 7a&es pro<ra7in< easier. )u e !5: *o not 8ard -ode te;t siEes or font na7es. Rationale 08e a9ai abi ity of font sty es and siEes depends on t8e under yin< 8ardware and software p atfor7# as we as on t8e -urrent settin<s of t8e :a9a runti7e en9iron" 7ent. /se t8e :a9a ibrary to <et 7etri-s infor7ation fro7 any fonts you use# and re y on t8at infor7ation for ayin< out t8e -orrespondin< te;ts. F8en se e-tin< a non" standard font (one not <uaranteed to be a9ai ab e on e9ery p atfor7) 7a&e sure t8at a reasonab e standard rep a-e7ent wi be used if t8e font is not a9ai ab e. )u e !>: *o not 8ard -ode -o ors or ot8er 5/I appearan-e e e7ents. Rationale 08e nu7ber of a9ai ab e -o ors and t8e a-tua -o or pa ette a9ai ab e -8an<es dependin< of t8e p atfor7. A -o or se e-tion t8at wor&s adeHuate y in a -ertain p at" for7# 7ay render te;t or <rap8i-a e e7ents unreadab e or unre-o<niEab e in ot8er p atfor7. )u e !': *o not retain Rraphics obDe-ts passed to update 7et8ods of <rap8i-a -o7ponents. Rationale 08e standard AF0 1omponent.paint and 1omponent.update - ass 7et8" ods (a standard Swing -o7ponents are deri9ed fro7 - ass java.awt.1omponent) re-ei9e an obDe-t i7p e7entin< t8e Rraphics interfa-e as para7eter. 08is obDe-t is e;pe-ted t8e be 9a id on y for t8e duration of t8e -orre" spondin< paint or update operation. )etainin< it for usin< in subseHuent operations 7ay wor& on so7e p atfor7s and fai on ot8ers. 3 ample 08e fo owin< pattern s8ou d be a9oided:
Rraphics(retainedRraphics(-(null,( void(paint%Rraphics(g*( { ((((if(%retainedRraphics(--(null*( (((({ ((((((((retainedRraphics(-(g.create%*, ((((}( (end(if (retained'(do(not(do(this8
!!
((((
(painting(code(goes(here
((((... } // end uidelines for Developing Pure Programs
)u e !!: *o not use 7et8ods 7ar&ed as depre-ated in t8e :a9a API. Rationale $et8ods 7ar&ed as depre-ated are s-8edu ed for re7o9a in future 9ersions of t8e API. )u e !=: *o not re y on t8e for7at of t8e resu t of t8e java.net.5net=ddress.get?ost4ame 7et8od. Rationale 08e a-tua for7at of t8e get?ost4ame 7et8od depends on t8e under yin< soft" ware and 8ardware p atfor7. So7eti7es it is Dust t8e si7p e 8ost na7e# w8ereas so7e ot8er ti7es it in- udes a fu y Hua ified do7ain na7e. )u e =0: A ways -8e-& for o-a a9ai abi ity of P u<<ab e 2oo& and ,ee (P2A,) - asses# and pro9ide a safe fa ba-& in -ase t8ey are not a9ai ab e. F8en settin< a parti-u ar P2A, - ass# -8e-& t8at it is bot8 a9ai ab e and sup" ported. If not# fa ba-& to one of t8e standard P2A,s. Rationale P u<<ab e 2oo& and ,ee (P2A,) - asses a ow for <rap8i-a e e7ents to ta&e a distin-ti9e appearan-e and be8a9ior (for e;a7p e t8ose of t8e under yin< operatin< syste7). .f -ourse# not a P2A, - asses are insta ed in a p atfor7s. E9en if you in" - ude P2A, - asses wit8 your pro<ra7Ms distribution# t8ey 7ay not wor& on parti-u ar p atfor7s. )u e =1: *o not 7i; - asses -o7pi ed a<ainst different 9ersions of t8e :a9a p at" for7. Rationale In so7e rare situations# bu< fi;es or subt e -8an<es between 9ersions of t8e :a9a p atfor7 7ay -ause prob e7s w8en - asses -o7pi ed a<ainst different 9ersions of t8e :a9a p atfor7 are used to<et8er.
BSSC 2005(2) Issue 1.0 C1AP0E) = )EA2"0I$E :A3A
!=
Chapter . Real1Time Java

.." #ntroduction
As a 9ery 8i<8" e9e pro<ra77in< an<ua<e# :a9a offers pro<ra77er and soft" ware 7aintenan-e produ-ti9ity benefits t8at ran<e fro7 two to ten"fo d o9er uses of C and C??. By -arefu y app yin< :a9a te-8no o<ies to e7bedded rea "ti7e syste7s# software en<ineers are ab e to de i9er 8i<8er software Hua ity# in-reased fun-tiona i" ty# and <reater ar-8ite-tura f e;ibi ity in software syste7s. 08e ru es and re-o77en" dations in t8is -8apter are oriented towards 7a&in< t8e use of :a9a for rea "ti7e sys" te7s i7p e7entation as effe-ti9e and re iab e as possib e.
..%
5 -ote on 5utomatic 0arbage Collection

.ne of t8e &ey reasons w8y :a9a de9e opers are 7ore produ-ti9e t8an C and C?? de9e opers is be-ause of auto7ati- <arba<e -o e-tion. A--ordin< to a study perfor7ed by +ero; Pa o A to )esear-8 Center in t8e ear y 1=!0s# auto7ati<arba<e -o e-tion redu-es pro<ra77in< effort asso-iated wit8 ar<e# -o7p e; soft" ware syste7s by appro;i7ate y 40W. 08ese benefits are a7p ified si<nifi-ant y in t8e :a9a en9iron7ent be-ause auto7ati- <arba<e -o e-tion is t8e foundation upon w8i-8 7i ions of ines of -o77er-ia off"t8e"s8e f software# in- udin< a of t8e stan" dard :a9a ibraries# are based. If you re7o9e <arba<e -o e-tion fro7 t8e :a9a en9i" ron7ent# not on y do you 7a&e it 7ore diffi-u t to de9e op new software# but you a so pre- ude t8e use of a e;istin< :a9a ibrary -ode. 08e power of <arba<e -o e-tion -o7es wit8 a -ost. 0raditiona :a9a i7p e7en" tations o--asiona y pause e;e-ution of :a9a t8reads to s-an a of 7e7ory in sear-8 of obDe-ts t8at are no on<er bein< used. 08ese pauses -an ast tens of se-onds wit8 ar<e 7e7ory 8eaps. $e7ory 8eaps ran<in< fro7 100 $bytes to a fu 5i<abyte are bein< used in -ertain 7ission"-riti-a syste7s. 08e (0"se-ond <arba<e -o e-tion pause ti7es e;perien-ed wit8 traditiona :a9a 9irtua 7a-8ines are in-o7patib e wit8 t8e rea "ti7e e;e-ution reHuire7ents of 7ost 7ission"-riti-a syste7s. Spe-ia rea "ti7e 9irtua 7a-8ines 8a9e been i7p e7ented to support pre" e7ptib e and in-re7enta operation of t8e <arba<e -o e-tor. Fit8 t8ese 9irtua 7a" -8ines# t8e interferen-e by <arba<e -o e-tion on app i-ation -ode -an be statisti-a y bounded# 7a&in< t8is approa-8 suitab e for soft rea "ti7e syste7s wit8 ti7in< -on" straints 7easured in t8e 8undreds of 7i-rose-onds. .ne of t8e -osts of auto7ati- <arba<e -o e-tion is t8e o9er8ead of i7p e7ent" in< s8arin< proto-o s between app i-ation t8reads. App i-ation t8reads are -ontinua " y 7odifyin< t8e way obDe-ts re ate to ea-8 ot8er wit8in 7e7ory# w8i e <arba<e -o " e-tion t8reads are -ontinua y tryin< to identify obDe-ts t8at are no on<er rea-8ed fro7 any t8reads in t8e syste7. 08is -oordination o9er8ead is one of t8e 7ain rea" sons t8at -o7pi ed :a9a pro<ra7s run at one t8ird to one 8a f of t8e speed of opti" 7iEed C -ode.
=0
08e -o7p e;ity of t8e <arba<e -o e-tion pro-ess and of any software t8at de" pends on <arba<e -o e-tion for re iab e e;e-ution is beyond t8e rea-8 of -ost"effe-" ti9e stati- ana ysis to <uarantee -o7p ian-e wit8 a 8ard rea "ti7e -onstraints. 08us# t8e use of auto7ati- <arba<e -o e-tion for software t8at 8as 8ard rea "ti7e -on" straints is not re-o77ended.
..*
Soft Real1Time Development 0uidelines

08e fo owin< <uide ines app y to soft rea "ti7e software de9e op7ent. )u e =2: /se t8e :a9a 2 Standard Edition (:2SE) p atfor7. Rationale 08e benefits t8at :a9a brin<s to soft rea "ti7e 7ission"-riti-a syste7s are 7ost re e9ant to ar<e# -o7p e;# dyna7i- app i-ations. Sin-e t8e :2$E p atfor7 repre" sents an in-o7patib e subset of fu :2SE# it does not pro9ide a--ess to :2SE"stan" dard C.0S ibrary -o7ponents. If app i-ations reHuire :2EE -apabi ities# obtain t8e spe-ifi- :2EE ibraries t8at are reHuired and run t8e7 on a soft rea "ti7e :2SE p at" for7. A ternati9e y# run t8e reHuired :2EE fun-tiona ity on traditiona (non rea "ti7e) :3$ p atfor7s w8i-8 -o77uni-ate wit8 t8e soft rea "ti7e :3$ 7a-8ines usin< )$I or ot8er networ&in< proto-o s. )u e =(: Base ine a parti-u ar 9ersion of t8e :2SE ibraries. Rationale ,or any <i9en de9e op7ent proDe-t# it is ne-essary to standardiEe on a parti-u ar 9ersion of t8e :2SE ibraries (1.2# 1.(# 1.4# 5.0X). *o-u7ent t8is de-ision to a de9e " opers and 7ana<ers. +ecommen!ation 21 Consi!er using <Face an! S=5 for Graphical 7ser Interfaces$ Rationale $ost 7ission"-riti-a software does rea "ti7e syste7s do reHuire <rap8i-a sour-e SF0 and :fa-e RSF0S ibraries -o7ponents. SF0 and :,a-e 7ay run Swing. not reHuire <rap8i-a user interfa-es. If soft user interfa-es# -onsider usin< t8e open" instead of t8e proprietary AF0 and Swing in ess 7e7ory and faster t8an AF0 and
)u e =4: /se -ooperatin< 8ard rea "ti7e -o7ponents to interfa-e wit8 nati9e -ode. Rationale 08e :%I proto-o introdu-es si<nifi-ant data 7ars8a in< o9er8ead w8en obDe-ts are s8ared between t8e :a9a and nati9e en9iron7ents. ,urt8er7ore# t8e s8arin< proto-o s 7ay e;pose :a9a obDe-ts and @pri9ateA 9irtua 7a-8ine data stru-tures to undis-ip ined C -o7ponents# introdu-in< t8e ris& t8at 7isbe8a9in< C -ode wi -o7" pro7ise t8e inte<rity of t8e 9irtua 7a-8ine en9iron7ent. E;perien-e of e;istin< -us" to7ers in se9era rea proDe-ts in9o 9in< 8undreds of 7an years of de9e op7ent do-" u7ent t8at t8ese ris&s are rea # 8a9in< -ost de9e op7ent tea7s si<nifi-ant effort and
=1
-a endar ti7e to -orre-t errors introdu-ed into t8e :a9a en9iron7ent by C de9e opers writin< :%I -o7ponents. Better perfor7an-e and stron<er separation of -on-erns is rea iEed by i7p e" 7entin< a interfa-es to nati9e -ode as -ooperatin< 8ard rea "ti7e -o7ponents. )u e =5: /se -ooperatin< 8ard rea "ti7e -o7ponents to i7p e7ent perfor7an-e" -riti-a -ode. If t8e t8rou<8put of -ertain soft rea "ti7e -o7ponents is not suffi-ient to 7eet perfor7an-e reHuire7ents# i7p e7ent t8e reHuired fun-tiona ity as -ooperatin< 8ard rea "ti7e -o7ponents. Rationale Be-ause t8e -ode <eneration 7ode for 8ard rea "ti7e -o7ponents does not need to -oordinate wit8 <arba<e -o e-tion# t8ese -o7ponents <enera y run two to t8ree ti7es faster t8an soft rea "ti7e :a9a -o7ponents. )u e =>: /se -ooperatin< 8ard rea "ti7e -o7ponents to intera-t dire-t y wit8 8ard" ware de9i-es. If t8e soft rea "ti7e -o7ponent needs to -o77uni-ate dire-t y wit8 8ardware de9i-es w8i-8 are not represented by operatin< syste7 de9i-e dri9ers# i7p e7ent t8e de9i-e dri9er as a -ooperatin< 8ard rea "ti7e -o7ponent. If t8e operatin< syste7 pro9ides a de9i-e dri9er t8at represents t8is de9i-e as a fi e# use t8e standard java.io(or(java.nio( ibraries to a--ess t8e de9i-e. If t8e operatin< syste7 pro" 9ides a de9i-e dri9er wit8 a different API t8an t8e fi e syste7# use a -ooperatin< 8ard rea "ti7e -o7ponent to i7p e7ent t8e interfa-e to t8e de9i-e dri9er. +ecommen!ation 2% +estrict the use of ad9an-ed li1raries$ Certain standard :a9a ibraries are not a9ai ab e in -ertain e7bedded en9iron" 7ents be-ause t8e under yin< operatin< syste7 or 8ardware is 7issin< desired -a" pabi ities. A7on< t8e ibraries t8at 7ay not be a9ai ab e on a p atfor7s# isted in de" -reasin< order of portabi ity -on-ern# are:
:,a-e and SF0 ibraries: 08ese <rap8i-a ibraries are on y a9ai ab e on sys" te7s t8at 8a9e <rap8i-a 8ardware and t8e S7T inte<ration software reHuired to dri9e t8e <rap8i-a 8ardware. java.nio ibraries: $any e7bedded operatin< syste7s do not support asyn" -8ronous I6.. java.io ibraries: So7e e7bedded tar<ets 8a9e no notion of stdin# stdout# or stderr. So7e e7bedded tar<ets 8a9e no notion of non"9o ati e fi e stora<e. java.net ibraries: So7e e7bedded tar<ets 8a9e no networ& -onne-ti9ity.
)e-o<niEe t8at t8e use of t8ese ibraries 7ay i7it t8e portabi ity of -ode and 7ay -ontribute to t8e future 7aintenan-e burden. )u e =': Iso ate :3$ dependen-ies. E;istin< soft rea "ti7e 9irtua 7a-8ines differ in 8ow t8ey support -ertain i7por" tant 7ission"-riti-a -apabi ities. Frap a :3$ dependen-ies in spe-ia - asses t8at
=2
-an be <i9en e;tra attention if t8e -ode 7ust be ported to a different :3$. Spe-ifiser9i-es t8at reHuire t8is 8and in< in- ude:
1i<8"pre-ision ti7in< ser9i-es: obtainin< rea "ti7e wit8 <reater pre-ision t8an 1 7sP drift"free sleep%*# wait%*# and join%* ser9i-es. CP/"ti7e a--ountin<: 1ow 7u-8 CP/ ti7e -onsu7ed by ea-8 t8readX 1ow 7u-8 CP/ ti7e -onsu7ed at ea-8 priority e9e X 5arba<e -o e-tion pa-in<: 1ow to 7onitor t8e 7e7ory a o-ation be8a9ior of t8e app i-ation software and t8e effe-ti9eness of 5CX 1ow to s-8edu e 5C to 7aintain pa-e wit8 a o-ation ratesX S-8edu in<: If a 9irtua 7a-8ine offers 8i<8" e9e s-8edu in< support# su-8 as ear iest"dead ine first or 7a;i7u7 a--rued uti ity s-8edu in<# t8e s-8edu in< and syn-8roniEation ser9i-es s8ou d be iso ated wit8in a -entra iEed API.
+ecommen!ation 23 Carefull& select an appropriate soft real-time )irtual machine$ .ne of t8e 7ost i7portant de-isions in deter7inin< t8e su--ess of a soft rea " ti7e :a9a de9e op7ent effort is t8e se e-tion of a suitab e :3$. Ea-8 de9e op7ent proDe-t 8as uniHue reHuire7ents and -onstraints# so it 7ay be ne-essary to indepen" dent y e9a uate t8e re e9an-e of 9arious a9ai ab e 9irtua 7a-8ine produ-ts for ea-8 de9e op7ent effort. In se e-tin< a 9irtua 7a-8ine# -onsider at 7ini7u7 ea-8 of t8e fo owin< issues:
)ea "0i7e <arba<e -o e-tion s8ou d 8a9e a 7a;i7u7 pree7ption aten-y and s8ou d be in-re7enta so t8at w8en t8e <arba<e -o e-tor is pree7pted by 8i<8" er priority app i-ation t8reads# it -an resu7e wit8 t8e ne;t in-re7ent of wor& w8en t8e app i-ation t8read re inHuis8es t8e CP/. 08e <arba<e -o e-tor s8ou d defra<7ent t8e 8eap in order to assure re iab e on<"runnin< operation. And it 7ust a--urate y re- ai7 a dead 7e7ory rat8er t8an re- ai7in< on y a -onser" 9ati9e appro;i7ation of t8e dead 7e7ory. ,ina y# it 7ust be pa-ed to assure t8at 7e7ory is re- ai7ed at rates -onsistent wit8 t8e app i-ationGs steady"state de7and for new 7e7ory a o-ation. P ease note t8at 9irtua 7a-8ines e;ist t8at do not need to be pa-ed. 08e rea ti7e <arba<e -o e-tor <uarantees for su-8 9irtua 7a-8ines t8at enou<8 7e7ory wi be re- ai7ed by tyin< 5C to a o-ation. If -ode is -o7pi ed w8en it is oaded# t8is is -a ed a oad ti7e -o7pi er. 2oad ti7e -o7pi ation is an o der te-8niHue used in ist i7p e7entations.
A syn-8roniEation o-&s 7ust i7p e7ent priority in8eritan-e. A wait Hueues 7ust be ordered a--ordin< to t8read priorities. 08e 9irtua 7a-8ine needs to pro9ide 7onitorin< fa-i ities to a ow super9isory t8reads to obser9e and 7easure t8e rea "ti7e resour-e reHuire7ents of indi9id" ua -o7ponents. A7on< reHuired -apabi ities are t8e abi ity to deter7ine 8ow 7u-8 CP/ ti7e is -onsu7ed by parti-u ar t8reads# 8ow 7u-8 CP/ ti7e is -on" su7ed by t8e <arba<e -o e-tion t8read(s)# t8e rates at w8i-8 parti-u ar t8reads are a o-atin< 7e7ory# and t8e tota a7ount of 7e7ory bein< retained as i9e.
=(
*eter7ine w8i-8 re ease e9e of t8e :2SE ibraries are reHuired for a parti-u ar proDe-t (1.2# 1.(# 1.4# 5.0X) and assure t8at t8e 9endor is ab e to support t8e de" sired ibrary 9ersion t8rou<8out t8e duration of your de9e op7ent proDe-t. Assure t8at t8e 9irtua 7a-8ine pro9ides ibraries for 8i<8"pre-ision ti7e 7ea" sure7ents# and for drift"free wait%*# join%*# and sleep%* ser9i-es. If t8e syste7 is stati-a y -o7pi ed and oaded# assure t8at t8e 9irtua 7a-8ine is supported by appropriate A8ead"of"0i7e -o7pi ation and in&in< too s. If t8e syste7 7ust dyna7i-a y oad -o7ponents# assure t8at t8e dyna7i- - ass oader -an be -onfi<ured to run at ower priority t8an t8e on<oin< rea "ti7e ap" p i-ation wor& oad. If t8e dyna7i- - ass oader 7ust perfor7 :I0 -o7pi ation# assure t8at t8e :I0 -o7pi er -an be -onfi<ured to support ea<er in&in< and trans ation# 7eanin< t8at a -o7ponents are fu y reso 9ed and trans ated w8en t8e first of t8e interdependent 7odu es is oaded# rat8er t8an deferrin< :I0 trans ation unti t8e 7o7ent ea-8 -ode 7odu e is first e;e-uted. So7e syste7s need to dyna7i-a y oad -o7ponents w8i-8 8a9e t8e7se 9es been a8ead"of" ti7e -o7pi ed. 3erify t8is -apabi ity is supported if re e9ant to your proDe-t re" Huire7ents. Assure t8at t8e 9irtua 7a-8ine in- udes ne-essary de9e op7ent too s# in- udin< sy7bo i- debu<<in< of bot8 interpreted and -o7pi ed -ode and run"ti7e perfor" 7an-e and 7e7ory usa<e profi in<. If t8e p anned de9e op7ent proDe-t 7ay reHuire inte<ration wit8 -ooperatin< 8ard rea "ti7e -o7ponents# assure t8at t8e 9irtua 7a-8ine in- udes support for -ooperatin< 8ard rea "ti7e :a9a -o7ponents.
..,
:ard Real1Time Development 0uidelines

08e fo owin< <uide ines app y to soft rea "ti7e software de9e op7ent. 08e re-" o77endations of t8is se-tion are based on standards for safety"-riti-a and 7ission" -riti-a :a9a w8i-8 are bein< de9e oped wit8in t8e .pen 5roup. )u e =!: /se a 8ard rea "ti7e subset of t8e standard :a9a ibraries. Rationale 08ere is no auto7ati- <arba<e -o e-tion in t8e 8ard rea "ti7e do7ain so 7any of t8e standard :a9a ibraries wi not fun-tion re iab y. .t8er 7oti9ations to restri-t usa<e of t8e standard ibraries are (1) to redu-e t8e standard 7e7ory footprint and (2) to redu-e t8e a7ount of -ode t8at 7ust be -ertified in -ase safety -ertifi-ation re" Huire7ents 7ust be satisfied. )u e ==: /se a 8ard rea "ti7e subset of t8e rea "ti7e spe-ifi-ation for :a9a. Rationale 08e fu )0S: in- udes 7any -apabi ities t8at are not portab e between different -o7p iant i7p e7entations. ,urt8er7ore# supportin< t8e fu <enera ity of t8e )0S: i7poses -ertain perfor7an-e" i7itin< restri-tions on t8e i7p e7entation.
BSSC 2005(2) Issue 1.0 C1AP0E) = )EA2"0I$E :A3A )u e 100: /se en8an-ed rep a-e7ents for -ertain )0S: ibraries.
=4
Certain )0S: ibraries a-& t8e features desired for 8ard rea "ti7e and safety" -riti-a de9e op7ent. Ana o<ous rep a-e7ent ibraries are a9ai ab e in t8e javax.realtime.util.sc pa-&a<e. /se t8ese rep a-e7ent ibraries instead of t8e traditiona )0S: ibraries. 08e spe-ifi- rep a-e7ent ibraries# w8i-8 differ on y s i<8t y fro7 t8eir )0S: -ounterparts# are isted be ow:
=bsoluteTime =periodic#arameters =syncEvent 3ound=syncEvent?andler 1loc< ?ighResolutionTime 4o?eapRealtimeThread OneShotTimer #eriodic#arameters #eriodicTimer RelativeTime Release#arameters Si$eEstimator Sporadic#arameters Timer
)u e 101: Assure a9ai abi ity of supp e7enta ibraries. If parti-u ar app i-ations reHuire additiona ibraries beyond t8is 7ini7a set# as" sure t8at t8e ibraries are a9ai ab e for a intended tar<et p atfor7s. )u e 102: /se an inte i<ent in&er and annotations to <uide initia iEation of stati9ariab es. In traditiona :a9a# - ass 9ariab es are to be initia iEed @i77ediate y before first useA. 08is reHuires run"ti7e -8e-&s# introdu-es non"deter7inis7 into t8e worst"-ase e;e-ution"ti7e ana ysis# and 8inders effi-ient trans ation of pro<ra7s for nati9e e;e" -ution. ,urt8er# it introdu-es -ertain ra-e -onditions in w8i-8 t8e initia 9a ues of par" ti-u ar - ass 9ariab es (e9en t8e 9a ues of -ertain final 9ariab es) depend on t8e se" Huen-e in w8i-8 - asses are a--essed (and initia iEed). /se an inte i<ent stati- in&er <uided by LStaticHependency and L5nitiali$e=tStartup annotations to per" for7 initia iEation of a stati- 9ariab es. %ote: Sti an open issue for safety"-riti-a app i-ations in t8e .pen 5roup )0 :a9a ,oru7 pro-ess.
BSSC 2005(2) Issue 1.0 C1AP0E) = )EA2"0I$E :A3A )u e 10(: /se on y 12! priority e9e s for 4o?eapRealtimeThread.
=5
08e offi-ia )0S: spe-ifi-ation states t8at a -o7p iant i7p e7entation 7ust pro" 9ide at east 2! priorities# but 7ay support 7any 7ore. ,or 8ard rea "ti7e 7ission" -riti-a de9e op7ent# app i-ation software s8ou d i7it its use of priorities to t8e ran<e fro7 1 t8ou<8 12!. 3endors -an readi y support t8is priority ran<e as a standard 8ard rea "ti7e 7ission"-riti-a p atfor7. )u e 104: *o not instantiate java.lang.Thread or javax.realtime.RealtimeThread. 08e on y t8reads a owed to run in a 8ard rea "ti7e pro<ra7 are instan-es of 4o?eapRealtimeThread. )u e 105: Prea o-ate Throwable instan-es. Rationale 08e traditiona :a9a -on9ention of a o-atin< a new Throwable ea-8 ti7e an e;-eptiona -ondition is en-ountered is not -o7patib e wit8 i7ited"7e7ory 8ard rea "ti7e de9e op7ent pra-ti-es. Prea o-ate ne-essary Throwable obDe-ts in s-opes t8at are suffi-ient y 9isib e t8at t8ey -an be seen by t8e intended catch state7ent. 08row t8e prea o-ated 5mmortal2emory Throwable instan-es a9ai " ab e in javax.realtime.util.sc.#reallocatedExceptions w8en appropri" ate. )u e 10>: )estri-t a--ess to Throwable attributes. Rationale In a traditiona :a9a en9iron7ent# 7e7ory is a o-ated to represent pri9ate infor" 7ation asso-iated wit8 ea-8 t8rown Throwable. Be-ause a 8ard rea "ti7e en9iron" 7ent is assu7ed to 8a9e i7ited 7e7ory resour-es and no auto7ati- <arba<e -o " e-tion# t8e typi-a 8ard rea "ti7e pro<ra77in< sty e a9oids a o-ation of 7e7ory for ea-8 t8rown e;-eption. .ne fi;ed"siEe buffer 8o din< up to 20 Stac<TraceElement obDe-ts is 7aintained for ea-8 t8read. Ea-8 ti7e an e;-ep" tion is t8rown# t8is buffer is o9erwritten wit8 no 7ore t8an 20 of t8e inner"7ost nest" ed 7et8od a-ti9ation fra7es. 08e bufferGs -ontents -an be -opied by in9o&in< Throwable.getStac<Trace%* before any ot8er throw state7ents are e;e-uted by t8e t8read. Any -ode t8at atte7pts to a--ess 7ore t8an 20 sta-& fra7es# or de" ays in9o-ation of Throwable.getStac<Trace%* unti after a se-ond Throwable 8as been t8rown# wi not run re iab y in t8e 8ard rea "ti7e en9iron7ent. )u e 10': Annotate a pro<ra7 -o7ponents to Indi-ate s-oped 7e7ory be8a9iors. In order to enab e stati- ana ysis to pro9e referentia inte<rity wit8out t8e need for run"ti7e fet-8 and store -8e-&s# pro<ra77ers 7ust annotate t8eir software to identify 9ariab es t8at 7i<8t 8o d referen-es to obDe-ts a o-ated in te7porary 7e7o" ry s-opes.
BSSC 2005(2) Issue 1.0 C1AP0E) = )EA2"0I$E :A3A )u e 10!: Carefu y restri-t use of 7et8ods de- ared wit8 L=llow1hec<edScoped"in<s annotation. Rationale
=>
$et8ods wit8 t8is annotation 7ay ter7inate wit8 a run"ti7e e;-eption resu tin< fro7 inappropriate assi<n7ent operations. Auto7ated stati- ana ysis too s are not ab e to <uarantee t8e absen-e of t8ese run"ti7e e;-eptions# and referen-e assi<n" 7ent operations -ontained wit8in t8ese 7et8ods wi run s ower t8an ot8er -ode be" -ause ea-8 assi<n7ent 7ust be a--o7panied by a run"ti7e -8e-&. ,or ea-8 7et8od t8at is de- ared wit8 t8e L=llow1hec<edScoped"in<s annotation# pro" <ra77ers s8ou d pro9ide -o77entary e;p ainin< w8y t8ey be ie9e t8e -ode wi not 9io ate s-oped"7e7ory referentia inte<rity ru es. %ote: Sti an open issue for safety"-riti-a app i-ations in t8e .pen 5roup )0 :a9a ,oru7 pro-ess. )u e 10=: Carefu y restri-t use of 7et8ods de- ared wit8 L5mmortal=llocation annotation. As a ru e of t8u7b# 5mmortal2emory s8ou d on y be a o-ated durin< app i-a" tion startup. Any ot8er a o-ation of 5mmortal2emory introdu-es t8e ris& t8at t8e supp y of 5mmortal2emory wi be-o7e e;8austed in a on<"runnin< app i-ation. )u e 110: /se LStatic=naly$able annotation to identify 7et8ods wit8 bounded resour-e needs. 08e LStatic=naly$able annotation identifies 7et8ods t8at 8a9e bounded CP/ ti7e and 7e7ory needs. ,or any pro<ra7 -o7ponent de- ared wit8 t8e LStatic=naly$able annotation# pro<ra77ers s8ou d pro9ide Static"imit as" sertions to identify iteration i7its on oops and ot8er resour-e -onstraints. %ote: 08e definition of KStati-Ana yEab e is sti insuffi-ient y defined. F8at is stati-a y ana yEab e is 8i<8 y dependent on t8e too s a9ai ab e. 08e use of ibraries di-tates a notation about t8e order of e;e-ution of a 7et8od and t8e -orrespondin< dependen-ies so t8at t8e a-tua e;e-ution ti7e -an be deter7ined. ,or e;a7p e# t8ere 7ay be so7e stru-ture wit8 n e e7ents# and we &now t8e e e7ents -an be e;a7ined. 08at a one is not suffi-ient to <i9e a worst -ase e;e-ution ti7e# but if n is &now# t8en a 7a;i7u7 ti7e -an be deter7ined. A -o7bination of fun-tiona 9erifi-ation# data f ow ana ysis# and worst -ase e;e-ution ana ysis -an pro9ide su-8 an ana ysis. 08e i7portant point is t8at t8e -o7putationa effort and dependen-ies are &now. .ne -an say t8at a 7et8ods s8ou d 8a9e we defined resour-e usa<e bounds.
BSSC 2005(2) Issue 1.0 C1AP0E) = )EA2"0I$E :A3A )u e 111: /se 8ierar-8i-a or<aniEation of 7e7ory to support software 7odu es.
='
.r<aniEe software 7odu es to support 7odu ar -o7position of -o7ponents so t8at a 7e7ory a o-ation for indi9idua -o7ponents# in- udin< t8e 7e7ory for a of t8e t8reads t8at -o7prise t8e software 7odu e# is 8ierar-8i-a y or<aniEed. 08e 7e7ory for t8e -o7p ete 7odu e is in-re7enta y di9ided into 7e7ory for sub"7od" u es. Ea-8 sub"7odu e 7ay furt8er di9ide its 7e7ory for s7a er sub"7odu es. A 7e7ory re- a7ation is 8and ed in ast"in"first"out order wit8 respe-t to a o-ation se" Huen-e. )u e 112: /se t8e LTraditionalYavaShared -on9entions to s8are obDe-ts wit8 traditiona :a9a. F8en it is ne-essary or desirab e to s8are 8ard rea "ti7e data and6or -ontro abstra-tions wit8 t8e traditiona :a9a do7ain# use t8e LTraditionalYavaShared and LTraditionalYava2ethod annotations to arran<e t8e s8arin< of se e-ted ob" De-ts. %ote: Sti an open issue for safety"-riti-a app i-ations in t8e .pen 5roup )0 :a9a ,oru7 pro-ess. )u e 11(: A9oid synchroni$ed state7ents. F8en syn-8roniEation is reHuired# use synchroni$ed 7et8ods instead of indi" 9idua state7ents. )u e 114: In8erit fro7 #1# in any - ass t8at uses #riority1eilingEmulation 2onitor1ontrol po i-y. *e9e opers s8ou d de-ide w8en t8e syn-8roniEation -ode is written w8et8er it wi use #riority1eilingEmulation or #riority5nheritance 2onitor1ontrol po i-y. Code t8at intends to use #riority1eilingEmulation s8ou d in8erit fro7 t8e #1# interfa-e. )u e 115: In8erit fro7 =tomic in any - ass t8at syn-8roniEes wit8 interrupt 8an" d ers. 08e =tomic interfa-e e;tends t8e #1# interfa-e. 08e byte"-ode 9erifier en" for-es t8at a syn-8roniEed 7et8ods be on<in< to - asses t8at i7p e7ent Ato7i- are LStatic=naly$able in a e;e-ution 7odes. %ote: Sti an open issue in t8e .pen 5roup )0 :a9a ,oru7 pro-ess. )u e 11>: Annotate t8e ceiling#riority%* 7et8od of =tomic and #1# - asses wit8 L1eiling. 08e L1eiling annotation e;pe-ts its value attribute to be set to t8e -ei in< priority at w8i-8 t8is obDe-t e;pe-ts to syn-8roniEe. A9ai abi ity of an obDe-tGs intend" ed -ei in< priority as a sour-e -ode attribute 7a&es it possib e to pro9e -o7patibi ity between -o7ponents usin< stati- ana ysis too s. In parti-u ar# t8e stati- ana yEer -an de7onstrate t8at nested o-&s 8a9e stri-t y in-reasin< -ei in< priority 9a ues.
BSSC 2005(2) Issue 1.0 C1AP0E) = )EA2"0I$E :A3A )u e 11': *o not o9erride Object.finali$e%*.
=!
In traditiona :a9a -ode# an obDe-tGs finali$e%* 7et8od is in9o&ed by t8e <arba<e -o e-tor before t8e obDe-tGs 7e7ory is re- ai7ed. In t8e 8ard rea "ti7e do" 7ain# we do not 8a9e a <arba<e -o e-tor. $e7ory is re- ai7ed as parti-u ar -ontro -onte;ts are eft. If fina iEation -ode is reHuired# p a-e it in in t8e finally - ause of a try:finally state7ent. +ecommen!ation 24 7se !e)elopment tools to enforce consistenc& with har! realtime gui!elines$ 0o enfor-e t8at pro<ra77ers 7a&e proper use of t8e 8ard rea "ti7e API sub" sets and t8at a -ode is -onsistent wit8 t8e intent of t8e 8ard rea "ti7e pro<ra77in< annotations des-ribed in t8is se-tion# use spe-ia byte"-ode 9erifi-ation too s t8at 8e p assure re iab e and effi-ient i7p e7entation of pro<ra77er intent.
../
Safety1Critical Development 0uidelines

Safety"-riti-a de9e opers use a subset of t8e fu 8ard rea "ti7e 7ission"-riti-a -apabi ities. )u e 11!: E;-ept w8ere indi-ated to t8e -ontrary# use 8ard rea "ti7e pro<ra77in< <uide ines. In <enera # a of t8e 8ard rea "ti7e <uide ines are appropriate for safety"-riti-a de9e op7ent# e;-ept t8at -ertain pra-ti-es a--eptab e for 8ard rea "ti7e 7ission"-rit" i-a de9e op7ent s8ou d be a9oided wit8 safety"-riti-a software. )u e 11=: /se on y 2! priority e9e s for 4o?eapRealtimeThread. 08e offi-ia )0S: spe-ifi-ation states t8at a -o7p iant i7p e7entation 7ust pro" 9ide at east 2! priorities# but 7ay support 7any 7ore. ,or safety"-riti-a de9e op" 7ent# app i-ation software s8ou d i7it its use of priorities to t8e ran<e fro7 1 t8ou<8 2!. 3endors -an readi y support t8is priority ran<e as a standard safety"-riti-a p at" for7. )u e 120: Pro8ibit use of LOmitSubscript1hec<ing annotation. In safety"-riti-a -ode# turnin< off subs-ript -8e-&in< is stron< y dis-oura<ed# e9en t8ou<8 stati- ana ysis of t8e pro<ra7 presu7ab y 8as pro9en t8at t8e pro<ra7 wi not atte7pt to a--ess in9a id array e e7ents. In safety"-riti-a syste7s# t8e &ey benefit of subs-ript -8e-&in< is to pre9ent an error in one -o7ponent fro7 propa<at" in< to ot8er -o7ponents. %ote: C8e-&in< s8ou d on y be turned of auto7ati-a y by a -o7pi er t8at -an pro9e a <i9en -8e-& is unne-essaryY
)u e 121: Pro8ibit in9o-ation of 7et8ods de- ared wit8 L=llow1hec<edScoped"in<s annotation. 08is annotation is desi<ned to a ow pro<ra77ers to use pra-ti-es t8at -annot be -ertified safe by auto7ati- stati- t8eore7 pro9ers. 08us# t8ere is a ris& t8at any
==
software 7a&in< use of t8is annotation wi abort wit8 a run"ti7e e;-eption. A ow t8is pra-ti-e on y in safety"-riti-a syste7s for w8i-8 de9e opers are ab e to pro9ide abso" ute proof t8at run"ti7e e;-eptions wi not be t8rown. )u e 122: )eHuire a -ode to be LStatic=naly$able. In 8ard rea "ti7e 7ission"-riti-a -ode# t8e use of t8e LStatic=naly$able an" notation is entire y optiona . In safety"-riti-a -ode# we reHuire a -o7ponents to 8a9e t8is annotation# and for a re e9ant 7odes of ana ysis to 8a9e a true 9a ue for t8e enforce&analysis attribute. )u e 12(: )eHuire a - asses wit8 Synchroni$ed 7et8ods to in8erit #1# or =tomic. 08e safety"-riti-a profi e does not a ow t8e use of priority in8eritan-e o-&in<. %ote: Sti an open issue for safety"-riti-a app i-ations in t8e .pen 5roup )0 :a9a ,oru7 pro-ess. )u e 124: Pro8ibit dyna7i- - ass oadin<. F8i e dyna7i- - ass oadin< 7ay be supported in t8e 8ard rea "ti7e 7ission" -riti-a do7ain# it s8ou d be stri-t y a9oided in safety"-riti-a software. )u e 125: Pro8ibit use of b o-&in< ibraries. Be-ause of diffi-u ties ana yEin< b o-&in< intera-tion ti7es w8en software -o7" ponents -ontend for s8ared resour-es# a ser9i-es t8at 7i<8t b o-& are forbidden in safety"-riti-a -ode. Spe-ifi-a y# t8e fo owin< APIs s8ou d not be in9o&ed fro7 safe" ty"-riti-a app i-ation software:
java.lang.Object.wait%* java.lang.Object.wait%long* java.lang.Object.wait%long'(int* java.lang.Thread.join%* java.lang.Thread.join%long* java.lang.Thread.join%long'(int* java.lang.Thread.sleep%long* java.lang.Thread.sleep%long'(int* javax.realtime.util.sc.ThreadStac<.join%*,
)u e 12>: Pro8ibit use of #riority5nheritance(2onitor1ontrol po i-y. Priority in8eritan-e is 7ore diffi-u t to -ertify# 7ore -o7p i-ated to i7p e7ent# and ess effi-ient t8an priority -ei in< e7u ation. 08us# we pro8ibit its use in safety" -riti-a software syste7s.
100
)u e 12': *o not s8are safety"-riti-a obDe-ts wit8 a traditiona :a9a 9irtua 7a-8ine. Co7binin< safety"-riti-a -ode wit8 traditiona :a9a -ode usin< t8e LTraditionalYava2ethod and LTraditionalYavaShared -on9entions -o7" pro7ises t8e inte<rity of t8e safety"-ertifi-ation artifa-ts. 08is pra-ti-e is t8erefore stri-t y forbidden. +ecommen!ation 2# 7se !e)elopment tools to enforce consistenc& with safet&critical gui!elines$ 0o enfor-e t8at pro<ra77ers 7a&e proper use of t8e safety"-riti-a subset and t8at a -ode is -onsistent wit8 t8e intent of t8e 8ard rea "ti7e pro<ra77in< annota" tions des-ribed in t8is se-tion# use spe-ia byte"-ode 9erifi-ation too s t8at 8e p as" sure re iab e and effi-ient i7p e7entation of pro<ra77er intent.
BSSC 2005(2) Issue 1.0 C1AP0E) 10 E$BE**I%5 C?? .) C I% :A3A
101
Chapter "2 3mbedding C44 or C in Java

"2." #ntroduction
08ere are 7any e<a-y syste7s written in C and C??. So7eti7es t8e use of t8ese an<ua<es is preferred for nu7eri-a -a -u ations (7any ibraries e;ist) or for easy a--ess to 8ardware. So7eti7es it is a so -o7pany or proDe-t po i-y to write -ode in t8ese an<ua<es. It -an be a so ution to e7bed su-8 C6C?? -ode in :a9a usin< t8e :%I API# in or" der to 7a&e su-8 app i-ations interoperate wit8 :a9a app i-ations. .t8er so utions e;ist 8owe9er and are nor7a y preferab e to e7beddin< C6C?? -ode in :a9a# as su-8 e7beddin< is often -o7p e; and error"prone. 1owe9er# in so7e -ases# t8e dire-t e7beddin< of nati9e -ode be-o7es ne-es" sary for perfor7an-e reasons or to o9er-o7e t8e stri-t a--ess restri-tions t8at t8e :a9a en9iron7ent so7eti7es i7poses. If e7beddin< of C?? or C -ode is reHuired# t8ese <uide ines s8ou d 8e p to in-rease portabi ity# safety and perfor7an-e on dif" ferent :a9a p atfor7s.
"2.%
5lternatives to J-#
+ecommen!ation 22 8)oi! em1e!!ing CHH or C co!e in <a)a as much as possi1le$ 7se other coupling solutions instea! if CHH or C co!e nee!s to 1e integrate! to the software pro!uct$ Rationale E7beddin< C?? and C -ode in :a9a -an be done wit8 t8e :a9a %ati9e Interfa-e (:%I)"API. 1owe9er t8is API is 9ery -o7p e; and error"prone. It is better to interfa-e wit8 C6C?? 9ia C.)BA or 9ia +$2"fi es. 08is &eeps t8e C6C?? en9iron7ent suffi" -ient y separated fro7 t8e :a9a"p atfor7# and 8as t8e fo owin< ad9anta<es:
Better interoperabi ity 2ess errors :a9a"-o7ponent retains a t8e power of its obDe-t"oriented features 2ess -o7p e; t8an w8en usin< :%I Fe "defined interfa-es Interoperabi ity# se-urity and -o77uni-ation ser9i-es w8en C.)BA is used.
102
"2.*
Safety
C?? or C -ode is not -o9ered by t8e ad9an-ed safety features (a--ess -ontro # inde;# type and nu pointer -8e-&s# e;-eption 8and in<# et-.) :a9a de9e opers are used to. ,or -ode safety# t8ese -8e-&s need to be perfor7ed e;p i-it y by t8e de9e " oper. )u e 12!: /se t8e estab is8ed -odin< standards for C?? or C for t8e de9e op7ent of C?? or C -ode t8at is e7bedded into t8e :a9a -ode. Rationale )espe-tin< t8e estab is8ed -on9entions 8e ps to a9oid errors# eases under" standin< of t8e -ode by de9e opers wit8 a C?? or C ba-&<round in t8e area# and en" ab es interoperabi ity wit8 e;istin< C?? or C -ode. )u e 12=: C8e-& for ExceptionOccurred%* after ea-8 -a of a fun-tion in t8e :%I interfa-e if t8at 7ay -ause an e;-eption. Rationale ,un-tions a9ai ab e in t8e :%I interfa-e (as defined in C6C?? in- ude fi e Tjni.hT) often si<na an error -ondition to t8e -a er by storin< an e;-eption in t8e -urrent :%I en9iron7ent. /n i&e in :a9a -ode# t8is e;-eption is not t8rown and prop" a<ated auto7ati-a y to t8e ne;t surroundin< e;-eption 8and er t8at a--epts an e;" -eption of t8is &ind. Instead# e;e-ution of C?? or C -ode -ontinues nor7a y un ess t8ere is an e;p i-it -8e-& t8at no e;-eption o--urred. C8e-&in< for e;-eptions is t8erefore reHuired after ea-8 -a t8at 7ay -ause an e;-eption to indi-ate an error situation. C8e-&in< t8e return 9a ue of su-8 a -a is <enera y not suffi-ient. )u e 1(0: $ar& nati9e 7et8ods as private. Rationale %ati9e fun-tions 7ay perfor7 operations t8at are not safe wit8 respe-t to t8e -8e-&s perfor7ed by :a9a -ode. If pub i- a--ess to a nati9e fun-tion is reHuired# a wrapper fun-tion written in :a9a -an ensure t8at t8e -a is perfor7ed fro7 an en9i" ron7ent t8at <uarantees t8at t8e -a is safe.. 3 ample
private(static(native(int(nativeReadRegister%int(register*, public(static(int(readRegister%int(register*( { ((((int(result, ((((if(%is"egalRegister%register*(ZZ(isReady%register**( (((({ ((((((((result(-(nativeReadRegister%register*, ((((}( (end(if ((((else(

(((({ ((((((((throw(new(5llegal=rgumentException% ((((((((((((((((@register;(@.register*, ((((}( (end(else ((((return(result, }( (end(method
10(
)u e 1(1: Se e-t 7et8od na7es for C?? or C 7et8ods t8at state - ear y t8at su-8 a 7et8od is a nati9e 7et8od. Co77on 7eans to 7ar& a nati9e 7et8od are a 7et8od na7e t8at ends wit8 t8e -8ara-ter M0M or t8at starts wit8 t8e strin< Tnati9eT# e.<.# nativeReadRegister %* or readRegister/%*. Rationale $ar&in< nati9e 7et8ods a9oids -onfusion. )u e 1(2: A9oid na7e o9er oadin< for nati9e 7et8ods. Rationale 08e :%I na7e 7an< in< ru es for o9er oaded 7et8ods (7et8ods t8at 8a9e eHua na7e but different ar<u7ent ists) resu ts in 9ery -u7berso7e na7es. Addin< an o9er oaded nati9e 7et8od to an e;istin< - ass -auses rena7in< t8e C?? or C fun-tion of e;istin< nati9e 7et8ods t8at were not o9er oaded before# -ausin< diffi-u t in&in< prob e7s of t8e app i-ation. )u e 1((: *o not use wea& < oba referen-es. Rationale A wea& < oba referen-es obtain by 4ew7ea<RlobalRef%* 7ay -8an<e its 9a ue to null at any point in ti7e. 08is 7a&es error dete-tion and 8and in< e;tre7e" y diffi-u t. %ote: In <enera # t8is is a <ood ru eP 8owe9er# t8ere 7ay be -ases w8ere wea& referen-es are ne-essary to insure t8at ba-& pointers fro7 nati9e -ode do not pre9ent <arba<e -o e-tion. In t8at -ase# t8e -ode 7ust insure t8at w8ene9er t8e nati9e obDe-t is a9ai ab e# t8e ba-& pointer (wea& pointer) is 9a id. Sti e;p i-it dea o-ation of nati9e obDe-ts is preferred.
"2.,
!erformance
Perfor7an-e <ains -an be one i7portant reason to e7bed C?? or C -ode into :a9a -ode. 1owe9er# t8ere is additiona o9er8ead in9o 9ed in t8e use of :%I t8at 7ay wor& a<ainst t8e perfor7an-e <ained t8rou<8 t8e use of C?? or C -ode. 08e additiona o9er8ead fro7 :%I -an be e;p ained in 7any different ways::
104
)eferen-es passed to C?? or C -ode need to be prote-ted fro7 t8e <arba<e -o e-tor a-ti9ity. Parti-u ar y# t8e <arba<e -o e-tor 7ust not re- ai7 7e7ory of an obDe-t t8at is referen-ed fro7 :%I -ode and it -annot update a referen-e 9a " ue so it 7ay not 7o9e obDe-ts in order to defra<7ent 7e7ory. Sin-e :%I -ode 7ay run for an arbitrary a7ount of ti7e t8at is not &nown t8e to 3$# deta-8in< t8e t8read t8at perfor7s t8e :%I -a fro7 t8e rest of t8e 3$ 7ay be ne-essary in order to a9oid b o-&in< ot8er :a9a t8reads. 08e -a in< -on9entions of :%I are different fro7 t8e -a in< -on9entions t8at are used interna y by -o7pi ed or interpreted -ode runnin< wit8in t8e 3$. Spe-ia wrapper fun-tions are reHuired to interfa-e between t8e 3$ and nati9e 7et8ods -ausin< a 8i<8er -a o9er8ead -o7pared to nor7a :a9a 7et8od -a s.
+ecommen!ation 2> 8)oi! the use of CHH or C co!e em1e!!e! using the <FI to increase performance$ Rationale 08e additiona o9er8ead of :%I and t8e oss in safety and portabi ity are i&e y to -ounter t8e perfor7an-e <ain. +ecommen!ation 20 8)oi! passing reference )alues to nati)e co!e$ Rationale Passin< referen-e 9a ues to nati9e -ode -auses e;tra o9er8ead to prote-t t8ese referen-es fro7 <arba<e -o e-tion. ,urt8er7ore# referen-ed 9a ues -annot be used dire-t y wit8in :%I -ode# t8ey -an on y be a--essed t8rou<8 -a s to fun-tions in t8e :%I (as defined in Tjni.hT) -ausin< additiona o9er8ead. 3 ample *o not pass a referen-e to an instan-e of - ass #oint# but pass two inte<ers for t8e + any V -oordinate 9a ues instead. 08ese 9a ues -an t8en be used dire-t y in t8e nati9e -ode. )u e 1(4: /se Helete"ocalRef%* to free referen-es in nati9e -ode t8at were ob" tained in a oop. Rationale 08e prote-tion of referen-e 9a ues passed to nati9e -ode reHuires 7e7ory t8at needs to be a o-ated by t8e 3$. If referen-es are obtained in a oop# e9en if t8ese referen-es are a eHua as in repeated -a s to RetAield5d%* for t8e sa7e fie d# t8e 7e7ory t8at is reHuired to prote-t t8ese referen-es wi <row un ess t8e refer" en-es are re eased by -a s to Helete"ocalRef%*. )u e 1(5: /se 4ewRlobalRef%*6HeleteRlobalRef%* on y for referen-es t8at are stored outside of rea-8ab e 7e7ory t8at sur9i9es fro7 one :%I -a to t8e ne;t. Rationale 08e o9er8ead for -reation and de etion of a < oba referen-e is typi-a y si<nifi"
105
-ant y 8i<8er t8an t8at for o-a referen-es. ,urt8er7ore# a for<otten HeleteRlobalRef%* wi 7a&e it i7possib e for t8e 3$ to e9er re ease t8e 7e7o" ry t8at was prote-ted < oba y# -ausin< a 7e7ory ea&. +ecommen!ation 2? 8)oi! calling 1ac; into <a)a co!e from CDCHH co!e$ Rationale 08e :%I to :a9a -a in< -on9entions are different to t8e interna -a in< -on9en" tions used by t8e 3$ and reHuire spe-ia treat7ent. A -a of a :a9a 7et8od fro7 wit8in :%I -ode is typi-a y 7u-8 7ore e;pensi9e t8an t8e -orrespondin< -a fro7 wit8in :a9a -ode. +ecommen!ation >0 Put as much functionalit& as possi1le into the <a)a co!e an! as little as possi1le in the <FI co!e$ Rationale 2ar<er C??6C fun-tiona ity usua y i7p ies -o7p e;er intera-tions between C6C?? and :a9a -ode# w8i-8 in turn 7ay ead to 7ore errors# and redu-ed re iabi ity and effi-ien-y. 3 ample 08rowin< an e;-eption fro7 wit8in :%I -ode is a -o7p e; pro-edure# it is better defer t8is a-ti9ity to :a9a -ode t8at is si7p er. +ecommen!ation >1 8)oi! +et,ArrayElements)* an! +et,ArrayElementsCritical)* functions$ Rationale 08ese fun-tions 7ay reHuire a o-ation of te7porary arrays and -opyin< of t8e array -ontents into a te7porary array. 08e reasons for t8e need to -opy t8e data are t8at t8e interna representation of arrays t8at is used by t8e 9irtua 7a-8ine 7ay be different t8an a si7p e C?? or C array. ,urt8er7ore# t8e <arba<e -o e-tor 7ay 7o9e arrays w8en it is defra<7entin< t8e 8eap# w8i-8 wou d be i7possib e if C?? or C -ode 8o ds a dire-t referen-e to t8e array data. Apart fro7 t8e a o-ation and -opyin< o9er8ead# t8ese fun-tions 7ay fai due to 7e7ory fra<7entation or ow 7e7ory. 08ey are unsafe for on< runnin< app i-a" tions. +ecommen!ation >% 8)oi! fre"uent calls to the reflecti)e functions -indClass )*, +et.ethod/D)*, +et-ield/D)*, an! +etStatic-ield/D)*$ Rationale 08ese fun-tions perfor7 an e;pensi9e strin< sear-8. If freHuent a--esses to a - ass# 7et8od or fie d are reHuired# obtain t8ese 9a ues by a nati9e initia iEation fun-" tion# prote-t t8e7 9ia 4ewRlobalRef and store t8e resu ts in a data stru-ture a-" -essib e fro7 t8e -ode t8at needs to a--ess t8ese 9a ues.
10>
"2./
Lo6 Level :ard6are 5ccess

)u e 1(>: A9oid usin< :%I for nati9e 1F a--ess if a ternati9e 7eans are a9ai ab e. Rationale 08e Raw2emory=ccess - asses fro7 5he +eal 5ime Specification for <a)a R)0S:S pro9ide safe 7eans for dire-t 8ardware a--ess t8at a9oids t8e dan<er and o9er8ead in9o 9ed wit8 :%I -ode.
"2.)
-on1Standard -ative #nterfaces

So7e :a9a i7p e7entations pro9ide proprietary nati9e interfa-es in addition to t8e standard :%I. 08ese interfa-es 7ay pro9ide 8i<8er perfor7an-e sin-e t8ey 7ay use t8e sa7e interfa-e t8at is used by -o7pi ed :a9a -ode# t8ey -an a9oid t8e de" ta-8in< and atta-8in< o9er8ead fro7 t8e 3$ and t8ey -an a9oid t8e pointer re<ister" in< and unre<isterin< o9er8ead. 1owe9er# t8ese interfa-es are proprietary# i.e.# t8ey are not portab e between different 3$s. A so# -ode written for t8e7 is typi-a y 7ore -o7p e; sin-e 7any as" pe-ts of t8e interna s of t8e under yin< 3$ and <arba<e -o e-tor 7ay be e;posed. )u e 1(': *o not use non"standard nati9e interfa-es un ess t8ere are 9ery <ood reasons to do so. Rationale 5i9in< up on t8e portabi ity and -o7patibi ity wit8 ot8er :a9a en9iron7ents is a 7aDor disad9anta<e for a future reuse of t8e -ode. .n y if t8e a-8ie9ab e perfor" 7an-e usin< pure :a9a or :%I is abso ute y insuffi-ient to so 9e t8e prob e7 at 8and# t8e use of proprietary interfa-es 7ay be Dustified. )u e 1(!: )estri-t t8e use of non"standard nati9e interfa-e uses to as few fun-tions as possib e. Rationale E9en if t8e use of a non"standard nati9e interfa-e is reHuired at so7e point# t8is point s8ou d - ear y be iso ated fro7 t8e rest of t8e app i-ation. Su-8 7et8ods s8ou d be defined in a separate - ass t8at is - ear y do-u7ented to be dependent on t8e -orrespondin< 9irtua 7a-8ine. A ess -riti-a nati9e -ode s8ou d use t8e standard :%I to intera-t wit8 t8e :a9a -ode in a portab e way.
BSSC 2005(2) Issue 1.0 C1AP0E) 11 SEC/)I0V
10'
Chapter "" Security

""." #ntroduction
Se-urity is a -o7p e; area# w8i-8 nowadays represents a -on-ern for or<aniEa" tions of a siEes and in a fie ds of endea9or. ESA is no e;-eption. .n t8e one 8and# its internationa nature poses se-urity -8a en<es# and# on t8e ot8er 8and# se-urity p ays an i7portant ro e in ESAMs 5a i eo and 5$ES proDe-ts.) A t8ou<8 7a&in< a software syste7 se-ure <oes way beyond -odin<# adeHuate -odin< is sti funda7enta to a-8ie9e proper se-urity. 08e fo owin< ru es and re-o7" 7endations# are intended to fa-i itate produ-in< 7ore se-ure and re iab e :a9a -ode.
"".%
The Java Security ?rame6or@

08e standard :a9a p atfor7 (-o7pi er# byte-ode 9erifier# runti7e syste7) is de" si<ned to enfor-e t8e fo owin< ru es:
C ass 7e7ber a--ess (as defined by t8e private# protected# and public &eywords) is stri-t y ad8ered to. Pro<ra7s -annot a--ess arbitrary 7e7ory o-ations (pointers do not e;ist in standard :a9a). Entities t8at are de- ared as final -annot be -8an<ed. 3ariab es -annot be used before t8ey are initia iEed. Array bounds are -8e-&ed durin< a array a--esses. .bDe-ts of one type -annot be arbitrari y -ast into obDe-ts of ot8er types.
Additiona y# t8e p atfor7 i7p e7ents an e aborated a--ess -ontro 7e-8anis7# 7a&in< it possib e to restri-t a--ess to syste7 resour-es in a fine"<rained way. )ea "ti7e :a9a i7p e7entations 7ay not enfor-e so7e or a of t8ese restri-" tions. Parti-u ar y# it is typi-a for rea "ti7e :a9a app i-ations to dire-t y a--ess 7e7" ory o-ations in order to -ontro 8ardware de9i-es or read infor7ation fro7 t8e7.
"".*
!rivileged Code
:a9aMs a--ess -ontro syste7 is responsib e for prote-tin< syste7 resour-es fro7 unaut8oriEed a--ess. 08e basi- 7e-8anis7 used for t8is purpose is to <uaran" tee t8at all -ode tra9ersed by a t8read# up to t8e -urrent e;e-ution point# 8as appro" priate per7issions. It wi often be t8e -ase# t8ou<8# t8at a pro<ra7 needs to a--ess resour-es t8at it nor7a y -ou d not use# <i9en its per7issions. 08e pri9i e<ed b o-&s API RS/%Pri9S was desi<ned to 8and e su-8 situations in a se-ure# -ontro ed way.
10!
Code in a pri9i e<ed b o-& runs wit8 t8e per7issions <ranted to t8e b o-&# wit8" out ta&in< into a--ount t8e se-urity restri-tions of any -a er -ode. Pri9i e<ed b o-&s 7a&e t8e :a9a se-urity 7ode a ot 7ore f e;ib e# by 7a&in< it possib e to wrap po" tentia y inse-ure operations into -ode t8at# in so7e way or anot8er# restri-ts or -on" tro s a--ess to t8e7. 08is additiona f e;ibi ity -o7es# 8owe9er# at so7e -ost# be" -ause e9ery pri9i e<ed b o-& poses a -ertain se-urity ris& t8at 7ust be proper y as" sessed and 7ana<ed. +ecommen!ation >3 Ieep pri)ilege! co!e as short as possi1le$ Rationale Errors in pri9i e<ed -ode -an potentia y ead to se-urity e;p oits. ,or t8is rea" son# pri9i e<ed -ode s8ou d a ways be -arefu y audited (as opposite to Dust tested) before dep oyin< it. $a&in< pri9i e<ed -ode as s8ort as possib e# not on y si7p ifies t8e pro-ess of auditin< it# but redu-es t8e ris& of dan<erous errors bein< o9er oo&ed. +ecommen!ation >4 Chec; all uses of tainte! )aria1les in pri)ilege! co!e$ A 9ariab e used in a pri9i e<ed b o-& is -onsidered tainted# if it -ontains a 9a ue t8at was dire-t y passed as para7eter by t8e 7et8od -a er. Rationale A uses of tainted 9ariab es s8ou d be -arefu y -8e-&ed to 7a&e sure t8ey -an" not ead to inappropriate pri9i e<e es-a ation. 3 ample Consider t8e fo owin< 7et8od:
public(static(String(get#rop%final(String(name*( { ((((return(%String*(=ccess1ontroller.do#rivileged%new ((((((((((((#rivileged=ction%*( (((({ ((((((((public(Object(run%*( (({ (((((((((((( (FnameF(is(tainted'(beware8 ((((((((((((return(System.get#roperty%name*, ((((((((}( (end(method ((((}( (end(constructor }( (end(method
08e 9a ue of para7eter name wi be used dire-t y to retrie9e a property# wit8out i7posin< any restri-tions or 7a&in< any -8e-&s on it. 08is 7eans t8at any - ass be" in< ab e to -a t8is public 7et8od wi be ab e to retrie9e arbitrary properties. /ses of tainted 9ariab es in pri9i e<ed -ode 7ust a ways be -arefu y -8e-&ed. 1e per 7et8ods a owin< unrestri-ted a--ess to a resour-e s8ou d a ways be de" - ared private.
10=
"".,
Secure Coding
)u e 1(=: )efrain fro7 usin< non"final public static 9ariab es. Rationale It is i7possib e to -8e-& t8at -ode -8an<in< su-8 9ariab es 8as adeHuate per" 7issions. +ecommen!ation ># +e!uce the scope of metho!s as much as possi1le$ $a&e as few 7et8ods public as stri-t y ne-essary. A proper desi<n of - ass interfa-es done before i7p e7entin< t8e - ass s8ou d 8e p redu-e t8e nu7ber of public 7et8ods to a 7ini7u7. Rationale E9ery additiona pub i- 7et8od in-reases t8e ris& of unaut8oriEed a--ess to pri9i e<ed data# and 7a&es -ode auditin< 8arder. )u e 140: %e9er return referen-es to interna 7utab e obDe-ts -ontainin< sensiti9e data. Rationale Interna obDe-ts are part of t8e state of t8e obDe-t -ontainin< t8e7. )eturnin< referen-es to 7utab e interna obDe-ts 7a&es it possib e for a -a er to dire-t y a ter t8e obDe-tMs state# potentia y in dan<erous ways. Parti-u ar y# -ontainers i&e arrays# 9e-tors or 8as8 tab es are a ways 7utab e# e9en if t8e 9a ues stored in t8e7 are not. An atta-&er 8a9in< a--ess to a -ontainer of i77utab e 9a ues -annot -8an<e t8e 9a " ues dire-t y# but -an a ter t8e set of 9a ues stored in t8e -ontainer. )u e 141: %e9er store user pro9ided 7utab e obDe-ts dire-t y. Rationale /ser pro9ided 7utab e obDe-ts -ou d be intentiona y or unintentiona y 7odified after bein< stored# t8us indire-t y and une;pe-ted y affe-tin< t8e interna state of an obDe-t. Instead of storin< a referen-e to t8e user pro9ided obDe-t# a -opy (- one) s8ou d be 7ade an stored in its p a-e.
""./
SerialiBation
Seria iEed obDe-ts stored in a re<u ar fi e or tra9e in< a on< a networ& -onne;ion are outside of t8e -ontro of t8e :a9a runti7e en9iron7ent# and t8erefore not subDe-t to any of t8e se-urity 7easures pro9ided by t8e :a9a p atfor7. By a terin< seria iEed obDe-t data# an atta-&er -ou d possib y defeat se-urity 7easures t8at wou d ot8er" wise be adeHuate.
110
)u e 142: /se t8e transient &eyword for fie ds t8at -ontain dire-t 8and es to sys" te7 resour-es# or t8at -ontain infor7ation re ati9e to an address spa-e. Rationale A seria iEed 8and e to a fi e or ot8er syste7 resour-e# -ou d be a tered in order to <ain unaut8oriEed a--ess to syste7 resour-es on-e t8e obDe-t is deseria iEed. )u e 14(: *efine - ass spe-ifi- seria iEin<6deseria iEin< 7et8ods. Rationale 08e on y way to <uarantee t8at interna - ass in9ariants are sti 9a id after dese" ria iEin< and obDe-t# is to write a -usto7 deseria iEin< 7et8od t8at uses t8e Object5nputGalidation interfa-e to -8e-& in9ariants. +ecommen!ation >2 Consi!er encr&pting serialiCe! 1&te streams$ Rationale En-ryptin< a byte strea7 is an effe-ti9e way to prote-t it fro7 a--identa or 7a" i-ious a teration 8appenin< durin< t8e ti7e it is outside t8e :a9a runti7e en9iron" 7ent. /nfortunate y# en-ryption a so reHuires t8e app i-ation to ta&e -are of en-ryp" tion &ey 8and in<# in- udin< <eneratin< &eys# storin< t8e7# and passin< t8e7 to any app i-ations needin< to read t8e data. )u e 144: F8i e deseria iEin< an obDe-t of a parti-u ar - ass# use t8e sa7e set of re" stri-tions used w8i e -reatin< obDe-ts of t8e - ass. If you i7pose restri-tions on untrusted -ode to -reate obDe-ts of a -ertain - ass# enfor-e t8e sa7e restri-tions w8i e deseria iEin< su-8 obDe-ts. Rationale *eseria iEin< is Dust anot8er for7 of obDe-t -reation. 1a9in< a;er restri-tions w8i e deseria iEin< 7a&es any additiona restri-tions i7posed durin< obDe-t -reation superf uous. 3 ample If an app et -reates a fra7e# it wi a ways 8a9e a warnin< abe . If su-8 a fra7e is seria iEed# t8e app i-ation s8ou d 7a&e sure t8at it sti 8as t8e abe after bein< de" seria iEed.
"".)
-ative ;ethods and Security

+ecommen!ation >> Chec; nati)e metho!s 1efore rela&ing on them for pri)ilege! co!e$ %ati9e 7et8ods -an brea& se-urity in a 9ariety of ways. 08ey s8ou d be -8e-&ed for:
08eir return 9a ue.
111
08eir para7eters. F8et8er t8ey bypass se-urity -8e-&s. F8et8er t8ey are de- ared public# protected# private# .... F8et8er t8ey -ontain 7et8od -a s w8i-8 bypass pa-&a<e"boundaries# t8us by" passin< pa-&a<e prote-tion
"".$
:andling Sensitive #nformation

Sensiti9e infor7ation i&e user passwords or pri9ate en-ryption &eys 7ust be 8and ed wit8 parti-u ar -are. )u e 145: E;p i-it y - ear sensiti9e infor7ation fro7 7ain 7e7ory. Rationale Infor7ation stored in 7ain 7e7ory -ou d possib y be a--essed by atta-&ers <ainin< a--ess to 7e7ory pa<es after t8ey were used by t8e app i-ation. ,or t8is reason it is a ways indi-ated to e;p i-it y o9erwrite sensiti9e infor7ation as soon as it is not ne-essary any7ore. )u e 14>: A ways store sensiti9e infor7ation in 7utab e data stru-tures. Rationale I77utab e data stru-tures -annot be o9erwritten. Pro<ra7s -an on y de ete a referen-es to t8e7# and wait for t8e <arba<e -o e-tor to re ease (but not o9erwrite) t8eir 7e7ory at so7e unspe-ified ti7e afterwards. 08e en<t8 of t8is <arba<e -o e-" tion -y- e 7ay open a window of opportunity for atta-&ers to <et 8o d of t8e sensiti9e data. 3 ample /se String3uffer obDe-ts instead of String obDe-ts to store sensiti9e pass" words.
BSSC 2004(1) Issue 10 d5 BIB2I.5)AP1V
112
'ibliography
A$B A%0 A)% A7b er# S. =riting +o1ust <a)a Co!e .)1>$01!($ A7bySoft In-. 2000. http; www.ambysoft.com Yava1odingStandards.pdf 08e Apa-8e Ant ProDe-t. Jome Page$ http; ant.apache.org Arno d Q. et a . 5he <a)aK Programming 9anguage .3r! E!ition($ Addison" Fes ey# 2000.
A3SI Aerospa-e 3e8i- e Syste7s Institute (A3SI). Gui!e to the Certification of S&stems with Em1e!!e! '1:ect-'riente! Software .Lersion 1$#($ B2. B.2 B.. B/) B o-8# :. Effecti)e <a)a Programming 9anguage Gui!e. Addison"Fes ey# 2001. Bo e a 5. et a . 5he +eal-5ime Specification for <a)a$ Addison"Fes ey# 2000. Boo-8# 5. '1:ect-'riente! 8nal&sis an! 6esign with 8pplications .%n! E!ition($ Addison"Fes ey# 1==(. Bur&e E. et a . <a)a Extreme Programming# .G)ei y Z Asso-iates# 200(.
C.. Cooper# :. F. <a)a 6esign Patterns. Addison"Fes ey# 2000. ECSS"E40"1B European Spa-e A<en-y (ESA). Space engineering - Software - Part 1 Principles an! re"uirements .ECSS-E-40 Part 1B($ %o9e7ber 200(. ECSS"C"!0B European Spa-e A<en-y (ESA). Space Pro!uct 8ssurance .ECSS-/-00B(. .-tober 200(. 5A$ 5a77a# E. et a . 6esign Patterns$ Addison"Fes ey# 1==5. 5%/:A3A 08e 5%/ :a9a Pro<ra77in< Standard: 8ttp:66www.<nu.or<6software6- asspat86do-s68a-&in<.8t7 [SEC> 5.S 5)A 2AP $C2 $EV .AQ 5os in<# : et a . 5he <a)a 9anguage Specification .%n! E!ition($ Addison"Fes" ey# 2000. http; java.sun.com docs boo<s jls 5rand# $. Patterns in <a)a - Lolume 1 .%n! E!ition(. Fi ey# 2002. 2ap ante P. A. editor. 6ictionar& of Computer Science, Engineering, an! 5echnolog&$ C)C Press# 2001. $-2au<8 in# B. <a)a M 4B9$ .G)ei y Z Asso-iates# 2001. $eyer# B. '1:ect-'riente! Software Construction .%n! E!ition($ Prenti-e"1a # 1=='. .a&s# S. <a)a Securit&. .G)ei y Z Asso-iates# 2001.
BSSC 2005(2) Issue 1.0 BIB2I.5)AP1V
11(
..0iABoo& ,edera A9iation Ad7inistration (,AA). Jan!1oo; for '1:ect-'riente! 5echnolog& in 8)iation .''5i8($ 2004. ..0iAPa<e ,edera A9iation Ad7inistration (,AA). '1:ect-'riente! 5echnolog& in 8)iation =e1 Site$ http; shemesh.larc.nasa.gov foot )0S: )ea "0i7e for :a9a0$ E;pert 5roup. +5S< 5he +eal 5ime Specification for <a)a. https; rtsj.dev.java.net S/%*oSun $i-rosyste7s. Jow to =rite 6oc Comments for the <a)a!oc 5ool$ http; java.sun.com j0se javadoc writingdoccomments S/%Code Sun $i-rosyste7s. Co!e Con)entions for the <a)a Programming 9anguage. http; java.sun.com docs codeconv S/%:a9a 5os in<# :. et a . 5he <a)a 9anguage Specification .%n! E!ition($ Addison" Fes ey# 2000. http; java.sun.com docs boo<s jls S/%2oo& Sun $i-rosyste7s. <a)a 9oo; an! Feel 6esign Gui!elines$ http; java.sun.com products jlf S/%Pref Sun $i-rosyste7s. <a)a Preferences 8PI$ http; java.sun.com j0se 6.+.0 docs guide lang preference s.html S/%Pri9 Sun $i-rosyste7s. <a)a 8PI for Pri)ilege! Bloc;s$ http; java.sun.com j0se 6.+.0 docs guide security dopriv ileged.html S/%0e-8 Sun $i-rosyste7s. <a)a 5echnolog& Page. http; SF0 3E) Standard Fid<et 0oo &it (SF0) ProDe-t. Jome Page$ http; www.eclipse.org swt 3er7eu en# A. et a . 5he Elements of <a)a St&le$ Ca7brid<e /ni9ersity Press# 2000. java.sun.com

Java Coding Standards: BSSC 2005 (2) Issue 1.0

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Java Coding Standards: BSSC 2005 (2) Issue 1.0

Uploaded by

Copyright:

Available Formats

BSSC 2005(2) Issue 1.

Java Coding Standards

european space agency / agence spatiale europenne

BSSC 2005(2) Issue 1.0 *.C/$E%0 S0A0/S S1EE0

Document Status Sheet

0260262004 1=60(62004 2!60562004 (060>62004

BSSC 2005(2) Issue 1.0 0AB2E ., C.%0E%0S

42 44 45 4> 4> 4'

Chapter + !ortability ............................................................................................................................ +* !.1 !.2 Introdu-tion )u es !( !(

Chapter . Real1Time Java ................................................................................................................... .2

BSSC 2005(2) Issue 1.0 2IS0 ., )/2ES

BSSC 2005(2) Issue 1.0 2IS0 ., )/2ES

BSSC 2005(2) Issue 1.0 2IS0 ., )/2ES

BSSC 2005(2) Issue 1.0 2IS0 ., )/2ES

BSSC 2005(2) Issue 1.0 2IS0 ., )/2ES

BSSC 2005(2) Issue 1.0 2IS0 ., )/2ES

BSSC 2005(2) Issue 1.0 2IS0 ., )EC.$$E%*A0I.%S

BSSC 2005(2) Issue 1.0 2IS0 ., )EC.$$E%*A0I.%S

BSSC 2005(2) Issue 1.0 2IS0 ., )EC.$$E%*A0I.%S

BSSC 2005(2) Issue 1.0 2IS0 ., )EC.$$E%*A0I.%S

BSSC 2005(2) Issue 1.0 P)E,ACE

BSSC 2005(2) Issue 1.0 C1AP0E) 1 I%0).*/C0I.%

Chapter " #ntroduction

BSSC 2005(2) Issue 1.0 C1AP0E) 1 I%0).*/C0I.%

BSSC 2005(2) Issue 1.0 C1AP0E) 1 I%0).*/C0I.%

BSSC 2005(2) Issue 1.0 C1AP0E) 1 I%0).*/C0I.%

BSSC 2005(2) Issue 1.0 C1AP0E) 1 I%0).*/C0I.%

BSSC 2005(2) Issue 1.0 C1AP0E) 2 I%S0A22A0I.%# B/I2* A%* /P*A0ES

Chapter % #nstallation& 'uild and (pdates

BSSC 2005(2) Issue 1.0 C1AP0E) ( S./)CE C.*E S0)/C0/)E

Chapter * Source Code Structure

BSSC 2005(2) Issue 1.0 C1AP0E) ( S./)CE C.*E S0)/C0/)E

set6get .t8er 7et8ods

0eneral Code #ndentation Rules

Brea& after -o77as. Prefer

Brea& before operators. Prefer

(brea& before @.A) to

(brea& after @.A.)

So7e re7ar&s about t8e pre9ious 7ode :

)u e 11: ,or7at -o7pound state7ents a--ordin< to t8e fo owin< <uide ines:

if state7ent wit8 else:

BSSC 2005(2) Issue 1.0 C1AP0E) ( S./)CE C.*E S0)/C0/)E

for state7ents wit8out a body s8ou d be for7atted as fo ows:

Rationale ,or7attin< -on9entions are ne-essary to a-8ie9e -ode unifor7ity.

try state7ent wit8 finally - ause:

BSSC 2005(2) Issue 1.0 C1AP0E) ( S./)CE C.*E S0)/C0/)E

Rationale ,or7attin< -on9entions are ne-essary to a-8ie9e -ode unifor7ity.

'lan@ Lines and Spaces

Between se-tions of a sour-e fi e. Between - ass and interfa-e definitions.

BSSC 2005(2) Issue 1.0 C1AP0E) ( S./)CE C.*E S0)/C0/)E Rationale

)u e 21: A ways use a spa-e -8ara-ter:

BSSC 2005(2) Issue 1.0 C1AP0E) 4 %A$I%5

0eneral -aming Conventions

BSSC 2005(2) Issue 1.0 C1AP0E) 4 %A$I%5

Type& Class and #nterface -ames

Interfa-es de- arin< obDe-t -apabi ities:

BSSC 2005(2) Issue 1.0 C1AP0E) 4 %A$I%5

BSSC 2005(2) Issue 1.0 C1AP0E) 4 %A$I%5

)u e (4: /se 9erbs in i7perati9e for7 to na7e 7et8ods t8at:

$et8ods wit8 border effe-ts:

BSSC 2005(2) Issue 1.0 C1AP0E) 4 %A$I%5 3 ample

Rationale 08e @setA -on9ention is wide y a--epted by t8e :a9a -o77unity.

BSSC 2005(2) Issue 1.0 C1AP0E) 4 %A$I%5 3 ample

BSSC 2005(2) Issue 1.0 C1AP0E) 5 .C/$E%0A0I.% A% C.$$E%0I%5 C.%3E%0I.%S

BSSC 2005(2) Issue 1.0 C1AP0E) 5 .C/$E%0A0I.% A% C.$$E%0I%5 C.%3E%0I.%S