A good de ve l
ope r k now s th at
th e re is m ore to de ve l
opm e nt
th an program m ing.
A gre at de ve l
ope r k now s th at
th e re is m ore to de ve l
opm e nt
th an de ve l
opm e nt.
W h e n you go agains t a s tandard,
docum e nt it. Al
ls tandards , e xce pt for
th is one , can be brok e n. You m us t
docum e nt w h y you brok e th e
s tandard, th e pote ntialim pl
ications
of bre ak ing th e s tandard, and any
conditions th at m ay/m us t occur
be fore th e s tandard can be appl
ie d to
th is s ituation.
Ite m
Exam pl
e
JAVA NAM ING
CO NVENTIO NS
Al
w ays us e (a fe w e xce ptions dis cus s e d
be l
ow ) ful
lEngl
is h de s criptors . Us e l
ow e r
cas e l
e tte rs in ge ne ral
, but capital
ize th e
firs t l
e tte r of cl
as s /inte rface nam e s and
th e firs t l
e tte r of any non-initialw ord
Ge ne ralConce pts
Us e te rm inol
ogy appl
icabl
e to th e dom ain
Us e m ixe d cas e for re adabil
ity
Us e s h ort form s s paringl
y and inte l
l
ige ntl
y
Avoid l
ong nam e s (< 15 ch aracte rs )
Avoid nam e s th at are s im il
ar or
diffe r onl
y in cas e
Nam ing conve ntion
Argum e nts /
param e te rs
cus tom e r , account , - or
- aCus tom e r , anAccount
Ful
lEngl
is h de s cription of val
ue /obje ct be ing
pas s e d, pos s ibl
y pre fixing th e nam e w ith ‘a’ or ‘an.’
Fie l
ds /prope rtie s
firs tNam e , l
as tNam e ,
w arpSpe e d
Ful
lEngl
is h de s cription, 1s t l
e tte r l
ow e rcas e ,
1s t l
e tte r of any non-initialw ord in uppe rcas e
Bool
e an ge tte r
is Pe rs is te nt() , is String()
m e m be r functions
, is Ch aracte r()
Pe fixe d w ith ‘is ’
Cl
as s e s
Cus tom e r ,
Savings Account
Ful
lEngl
is h de s cription, w ith th e firs t l
e tte rs
of al
lw ords capital
ize d
Com pil
ation unit
fil
es
Savings Account.java ,
Singl
e ton.java
Nam e of cl
as s /inte rface ;if > 1 cl
as s in fil
e , pre fixe d
w ith ‘.java’ to indicate it's a s ource code fil
e.
Com pone nts /
w idge ts
ok Button , cus tom e rLis t ,
fil
e M e nu
Ful
lEngl
is h de s cription de s cribing us age ;type
of th e com pone nt concate nate d onto th e e nd.
Contructors
Cus tom e r() ,
Savings Account()
Us e th e nam e of th e cl
as s
D e s tructors
final
ize ()
W il
linvok e final
ize () m e m be r function be fore
an obje ct is garbage col
l
e cte d
Exce ptions
e
It is ge ne ral
l
y acce pte d to us e th e l
e tte r ‘e ’
to re pre s e nt e xce ptions
FinalStatic fie l
ds
/cons tants
M IN_BALANCE ,
D EFAULT_D ATE
Uppe rcas e l
e tte rs , w ords s e parate d by unde rs core s . Be tte r: finals tatic ge tte r m e m be r functions
Ge tte r m e m be r
functions
ge tFirs tNam e () ,
ge tW arpSpe e d()
Pre fix th e nam e of th e fie l
d be ing acce s s e d
w ith ‘ge t’
Inte rface s
Runnabl
e , Prom pte r ,
Singl
e ton
Ful
lEngl
is h de s cr. conce pt of inte rface , 1s t l
e tte rs
of w ords cap'd. Pos tfix nam e w ith ‘abl
e ,’ ‘ibl
e ,’ or ‘e r’
Localvariabl
es
grandTotal, cus tom e r ,
ne w Account
Ful
lEngl
is h de s cription, 1s t l
e tte r in l
ow e r
cas e but do not h ide e xis ting fie l
ds /fie l
ds
Loop counte rs
i , j, k , counte r
It is ge ne ral
l
y acce pte d to us e th e l
e tte rs i , j
, or k , or th e nam e ‘counte r .’
Pack age
ca.uvic.ne ptune .pe rs is te nce .m apping
Se e Cl
as s e s - Gl
obalpack age s : re ve rs e nam e
of Inte rne t dom ain & pos tfix th e pack age nam e .
M e m be r Functions ope nFil
e () , addAccount()
Se tte r m e m be r
functions
s e tLas tNam e () ,
s e tW arpSpe e d()
Ful
lEngl
is h de s cription of w h at it doe s s tarting
w ith active ve rb if pos s ibl
e , 1s t l
e tte r in l
ow e r cas e
Pre fix th e nam e of th e fie l
d be ing acce s s e d
w ith ‘s e t’
JAVA D O CUM ENTATIO N
CO NVENTIO NS
Rul
e of th um b : if you’ve ne ve r s e e n th e
code be fore , w h at docum e ntation w oul
d
you ne e d to q uick l
y unde rs tand it
Ge ne ralConce pts
Com m e nts s h oul
d add to cl
arity
If it is n’t w orth docum e nting,
it is n’t w orth running
No de coration /banne r-l
ik e com m e nts
Ke e p com m e nts s im pl
e
W rite docum e ntation b e fore w riting code
W h y ~ not W h at
JAVA CO D ING
CO NVENTIO NS
9 9 .9 % of th e tim e it is m ore im portant
to program for your fe l
l
ow
de ve l
ope rs th an for th e m ach ine
Your code m us t b e
unde rs tandab l
e to oth e rs
Java com m e nt type s
D ocum e ntation Im m e diate l
y be fore de cl
arations
of inte rface s , cl
as s e s , m e m be r
functions and fie l
ds to docum e nt
th e m . Th e s e are proce s s e d by
javadoc to cre ate e xte rnal
docum e ntation for a cl
as s .
C Styl
e C-s tyl
e com m e nts to dis abl
e
l
ine s of code th at are no l
onge r
appl
icabl
e , but th at you w ant to
k e e p jus t in cas e ~ or w h il
e
de bugging.
Singl
e l
ine Us e s ingl
e l
ine com m e nts
inte rnal
l
y w ith in m e m be r
functions to docum e nt bus ine s s
l
ogic, code s e ctions and
de cl
arations of te m porary
variabl
e s.
/**
Customer – A customer is any
person or organization that we
sell services and products to.
@author S.W. Ambler
*/
/*
Commented out by J.T. Kirk on 1/1/03
replaced by preceding code. Delete
after 2 years if still not applicable
. . . (the source code )
*/
//
//
//
//
Apply a 5% discount to all
invoices over $1000 as defined by
the Sarek generosity campaign
started in Feb 1995
Argum e nts /param e te rs Th e type of th e param e te r
W h at it s h oul
d be us e d for
Any re s trictions or pre conditions
Exam pl
es
W H AT to
Fie l
ds /prope rtie s Its de s cription
D ocum e nt al
lappl
icabl
e invariants
docum e nt
Exam pl
es
Concurre ncy is s ue s
Vis ibil
ity de cis ions
Cl
as s e s Th e purpos e of th e cl
as s
Know n bugs
Th e de ve l
opm e nt/m ainte nance h is tory of th e cl
as s
D ocum e nt appl
icabl
e invariants
Th e concurre ncy s trate gy
Com pil
ation units Each cl
as s /inte rface de fine d in th e cl
as s , incl
. a brie f de s cription
Th e fil
e nam e and/or ide ntifying inform ation
Copyrigh t inform ation
Ge tte r m e m b e r function D ocum e nt w h y l
azy initial
ization w as us e d, if appl
icabl
e
Inte rface s Th e purpos e
H ow it s h oul
d and s h oul
dn’t be us e d
Localvariab l
e s Its us e /purpos e
M e m b e r Functions W h at and w h y th e m e m be r function doe s w h at it doe s
(D ocum e ntation) W h at a m e m be r function m us t be pas s e d as param e te rs
W h at a m e m be r function re turns
Know n bugs
Any e xce ptions th at a m e m be r function th row s
Vis ibil
ity de cis ions
H ow a m e m be r function ch ange s th e obje ct
Incl
ude a h is tory of any code ch ange s
Exam pl
e s of h ow to invok e th e m e m be r function if appropriate
Appl
icabl
e pre conditions and pos tconditions
D ocum e nt al
lconcurre ncy
M e m b e r Functions Controls tructure s
(Inte rnalcom m e nts ) W h y, as w e l
las w h at, th e code doe s
Localvariabl
es
D ifficul
t or com pl
e x code
Th e proce s s ing orde r
Pack age Th e rational
e for th e pack age
Th e cl
as s e s in th e pack age
Acce s s or m e m b e r functions
Cons ide r us ing l
azy initial
ization for fie l
ds in th e databas e
Us e acce s s ors for obtaining and m odifying al
lfie l
ds
Us e acce s s ors for ‘cons tants ”
For col
l
e ctions , add m e m be r functions to ins e rt and
re m ove ite m s
W h e ne ve r pos s ibl
e , m ak e acce s s ors prote cte d, not publ
ic
ds s h oul
d al
w ays be de cl
are d private
Fie l
ds Fie l
D o not dire ctl
y acce s s fie l
ds , ins te ad us e acce s s or
m e m be r functions
D o not us e finals tatic fie l
ds (cons tants ), ins te ad us e
acce s s or m e m be r functions
D o not h ide nam e s
Al
w ays initial
ize s tatic fie l
ds
Cl
as s e s
Localvariab l
es
M inim ize th e publ
ic and prote cte d inte rface s
D e fine th e publ
ic inte rface for a cl
as s be fore you be gin
coding it
D e cl
are th e fie l
ds and m e m be r functions of a cl
as s in th e
fol
l
ow ing orde r:
· cons tructors
· final
ize ()
· publ
ic m e m be r functions
· prote cte d m e m be r functions
· private m e m be r functions
· private fie l
d
D o not h ide nam e s
D e cl
are one l
ocalvariabl
e pe r l
ine of code
D ocum e nt l
ocalvariabl
e s w ith an e ndl
ine com m e nt
D e cl
are l
ocalvariabl
e s im m e diate l
y be fore th e ir us e
Us e l
ocalvariabl
e s for one th ing onl
y
M e m b e r functions D ocum e nt your code
Paragraph your code
Us e w h ite s pace , one l
ine be fore controls tructure s and tw o
Th is te xt is a s um m ary of be fore m e m be r function
Scott Am b l
e r's 'W riting
de cl
arations
Rob us t Java Code '
A m e m be r function s h oul
d be unde rs tandabl
e in l
e s s th an
th irty s e conds
Th e Am b ySoft Inc.
W rite s h ort, s ingl
e com m and l
ine s
Coding Standards for
Re s trict th e vis ibil
ity of a m e m be r function as m uch as
Java - v17.01d
pos s ibl
e
Th is l
ayout b y M aik e D ul
k Spe cify th e orde r of ope rations