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