A good de v el ope r k now s t h at t h e re is m ore t o de v el opm e nt t h an program m ing. A gre at de v el ope r k now s t h at t h e re is m ore t o de v el opm e nt t h an de v el opm e nt .

W h e n you go agains t a s t andard, docum e nt it . Al l st andards , e xce pt f or t h is one , can be brok e n. Y ou m us t docum e nt w h y you brok e t he st andard, t h e pot e nt ial im pl icat ions of bre ak ing t h e st andard, and any condit ions t h at m ay/ m us t occur be f ore t h e st andard can be appl ie d t o t h is s it uat ion.

J AV A NAM ING CO NV ENTIO NS

Al w ays us e (a f e w e xce pt ions dis cus s e d be l ow ) f ul l Engl is h de s cript ors . Us e l ow e r cas e l et t e rs in ge ne ral , but capit al ize t he f irs t l et t e r of cl as s /int e rf ace nam e s and t he f irs t l et t e r of any non-init ial w ord

Ge ne ral Conce pt s
Us e t e rm inol ogy appl icabl e t ot h e dom ain Us e m ixe d cas e f or re adabil it y Us e s h ort f orm s s paringl y and int el l ige nt l y Av oid l ong nam e s (< 15 ch aract e rs ) Av oid nam e s t h at are s im il ar or dif f e r onl y in cas e

I te m
Argum e nt s/ param e t e rs F ie l ds /prope rt ie s

Exam pl e
cus t om e r , account , - or - aCus t om e r , anAccount f irs t Nam e , l as t Nam e , w arpSpe e d

Nam ing conv e ntion

F ul l Engl is h de s cript ion of val ue / obj e ct be ing pas s e d, pos s ibl y pre f ixing t h e nam e w it h a or an. F ul l Engl is h de s cript ion, 1s t l et t erl ow e rcas e , 1s t l et t e r of any non-init ial w ord in uppe rcas e P ef ixe d w it h is F ul l Engl is h de s cript ion, w it h t he f irs t l et t e rs of al l w ords capit al ize d Nam e of cl as s / int e rf ace ;if > 1 cl as s in f il e , pre f ixe d w it h .j ava t o indicat e it 's a s ource code f il e. F ul l Engl is h de s cript ion de s cribing us age ;t ype of t h e com pone nt concat e nat e d ont ot h e e nd. Us e t h e nam e of t h e cl as s W il l inv ok e f inal ize () m e m be r f unct ion be f ore an obj e ct is garbage col l e ct ed It is ge ne ral l y acce pt edt o us e t he l et t e r e t o re pre s e nt e xce pt ions Uppe rcas e l et t e rs , w ords s e parat e d by unde rs core s . Be t t e r: f inal st at ic ge t t e r m e m be r f unct ions P re f ix t h e nam e of t he f ie l d be ing acce s s e d w it h ge t F ul l Engl is h de s cr. conce pt of int e rf ace , 1s t l et t e rs of w ords cap'd. P os tf ix nam e w ith abl e , ibl e , or e r F ul l Engl is h de s cript ion, 1s t l et t e r in l ow e r cas e but do not h ide e xis t ing f ie l ds / f ie l ds It is ge ne ral l y acce pt edt o us e t he l et t e rs i , j , or k , or t h e nam e count e r . Se e Cl as s e s - Gl obal pack age s : re v e rs e nam e of Int e rne t dom ain & pos t f ix t h e pack age nam e . F ul l Engl is h de s cript ion of w h at it doe s s t art ing w it h act iv e v e rb if pos s ibl e , 1s t l et t e r in l ow e r cas e P re f ix t h e nam e of t he f ie l d be ing acce s s e d w it h s e t

Bool e an ge t t er is P e rs is t e nt () , is St ring() m e m be r f unct ions , is Ch aract e r() Cl as s e s Com pil at ion unit f il es Com pone nt s / w idge t s Cont ruct ors De st ruct ors Exce pt ions F inal St at ic f ie l ds /cons t ant s Ge t t e r m e m be r f unct ions Int e rf ace s L ocal v ariabl es L oop count e rs P ack age Cus t om e r , Sav ings Account Sav ings Account .j av a, Singl et on.j av a ok But t on , cus t om e rL is t , f il e M e nu Cus t om e r() , Sav ings Account () f inal ize () e M IN_BAL ANCE , D EF AUL T_D ATE ge t F irs t Nam e () , ge t W arpSpe e d() Runnabl e ,P rom pt er, Singl et on grandT ot al , cus t om e r , ne w Account i , j, k , count er ca.uv ic.ne pt une .pe rs is t e nce .m apping

M e m be r F unct ions ope nF il e () , addAccount () Se t t e r m e m be r f unct ions se t L as t Nam e () , se t W arpSpe e d()

J AV A D O CUM ENT ATIO N CO NV ENTIO NS

Rul e of t h um b : if you v e ne v e r se e n t he code be f ore , w h at docum e nt at ion w oul d you ne e d t o q uick l y unde rs t and it

Ge ne ral Conce pt s
Com m e nt s s h oul d add t o cl arit y If it is n t w ort h docum e nt ing, it is n t w ort h running No de corat ion /banne r-l ik e com m e nt s Ke e p com m e nt s s im pl e W rit e docum e nt at ion b e f ore w rit ing code W h y ~ not W h at /** 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

J AV A CO D ING CO NV ENTIO NS
9 9 .9 % of t he t im e it is m ore im port ant t o program f or your f el l ow de v el ope rs t h an f or t h e m ach ine

Your code m us t b e unde rs t andab l e t o ot h e rs

Jav a com m e nt type s

D ocum e nt at ion Im m e diat el y be f ore de cl arat ions of int e rf ace s , cl as s e s , m e m be r f unct ions and f ie l ds t o docum e nt t h e m . Th e s e are proce s s e d by j av adoc t o cre at e e xt e rnal docum e nt at ion f or a cl as s . C St yl e C-s t yl e com m e nt s t o dis abl e l ine s of code t h at are no l onge r appl icabl e , but t h at you w ant t o keepj us 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 nt s int e rnal l y w it h in m e m be r f unct ions t o docum e nt bus ine s s l ogic, code s e ct ions and de cl arat ions of t e m porary v ariabl e s.
Acce s s or m e m b e r f unct ions Cons ide r us ing l azy init ial izat ion f or f ie l ds in t h e dat abas e Us e acce s s ors f or obt aining and m odif ying al l f ie l ds Us e acce s s ors f or cons t ant s F or col l e ct ions , add m e m be r f unct ions t o ins e rt and re m ov e it ems W h e ne v e r pos s ibl e , m ak e acce s s ors prot e ct e d, not publ ic

ie l ds s h oul d al w ays be de cl are d priv at e Fie l ds F D o not dire ct l y acce s s f ie l ds , ins t e ad us e acce s s or m e m be r f unct ions D o not us e f inal st at ic f ie l ds (cons t ant s ), ins t e ad us e acce s s or m e m be r f unct ions D o not h ide nam e s Al w ays init ial ize s t at ic f ie l ds Cl as s e s M inim ize t h e publ ic and prot e ct e d int e rf ace s De f ine t h e publ ic int e rf ace f or a cl as s be f ore you be gin coding it D e cl are t he f ie l ds and m e m be r f unct ions of a cl as s in t he f ol l ow ing orde r: cons t ruct ors f inal ize () publ ic m e m be r f unct ions prot e ct e d m e m be r f unct ions priv at e m e m be r f unct ions priv at e f ie l d D o not h ide nam e s D e cl are one l ocal v ariabl e pe r l ine of code D ocum e nt l ocal v ariabl e s w it h an e ndl ine com m e nt D e cl are l ocal v ariabl e s im m e diat el y be f ore t h e ir us e Us e l ocal v ariabl es f or one t h ing onl y

Argum e nt s /param e t e rs Th e t ype of t h e param e t er W h at it s h oul d be us e d f or Any re s t rict ions or pre condit ions Exam pl es W H AT t o Fie l ds / prope rt ie s It s de s cript ion D ocum e nt al l appl icabl e inv ariant s docum e nt Exam pl es Concurre ncy is s ue s V is ibil it y de cis ions Cl as s e s Th e purpos e of t h e cl as s Know n bugs Th e de v el opm e nt / m aint e nance h is t ory of t h e cl as s D ocum e nt appl icabl e inv ariant s Th e concurre ncy s t rat e gy Com pil at ion unit s Each cl as s / int e rf ace de f ine d in t h e cl as s , incl . a brie f de s cript ion Th e f il e nam e and/ or ide nt if ying inf orm at ion Copyrigh t inf orm at ion Ge t t e r m e m be r f unct ion D ocum e nt w h y l azy init ial izat ion w as us e d, if appl icabl e Int e rf ace s Th e purpos e H ow it s h oul d and s h oul dn t be us e d L ocal v ariab l e s It s us e / purpos e M e m b e r Funct ions W h at and w h y t h e m e m be r f unct ion doe s w h at it doe s (D ocum e nt at ion) W h at a m e m be r f unct ion m us t be pas s e d as param e t e rs W h at a m e m be r f unct ion re t urns Know n bugs Any e xce pt ions t h at a m e m be r f unct ion t h row s V is ibil it y de cis ions H ow a m e m be r f unct ion ch ange s t h e obj e ct Incl ude a h is t ory of any code ch ange s Exam pl e s of h ow t o inv ok e t h e m e m be r f unct ion if appropriat e Appl icabl e pre condit ions and pos t condit ions D ocum e nt al l concurre ncy M e m b e r Funct ions Cont rol st ruct ure s (Int e rnal com m e nt s ) W h y, as w e l l as w h at ,t h e code doe s L ocal v ariabl es D if f icul t or com pl e x code Th e proce s s ing orde r Pack age Th e rat ional e f or t h e pack age Th e cl as s e s in t h e pack age

L ocal v ariab l es

Me m be r f unct ions D ocum e nt your code P aragraph your code Us e w h it e s pace , one l ine be f ore cont rol st ruct ure s and t wo Th is t e xt is a s um m ary of be f ore m e m be r f unct ion Scot t Am b l e r's 'W rit ing de cl arat ions Rob us t J av a Code ' A m e m be r f unct ion s h oul d be unde rs t andabl e in l e ss t h an t h irt y s e conds Th e Am b ySof t Inc. W rit e s h ort , s ingl e com m and l ine s Coding St andards f or Re s t rict t he v is ibil it y of a m e m be r f unct ion as m uch as J av a-v 17.01d pos s ibl e yt h e orde r of ope rat ions Th is l ayout b y M aik e D ul k Spe cif