1. Why we have so unintuitive code at here 2. Why we cannot use best practice at here 3. Metadata of: parameters, returned value and exceptions 4. How API user should call your API
D a t e ( i n t y e a r , i n t m o n t h , i n t d a y ) { / / g i v e n p a r a m e t e r i s o n e - b a s e d , b u t w e n e e d z e r o - b a s e d v a l u e / / t o p l a y w i t h l e g a c y s y s t e m s a n d J a v a A P I t h i s . m o n t h = m o n t h - 1 ; }
* * T h i s m e t h o d s t i l l r e t u r n s n u l l ( n o t e m p t y O p t i o n a l ) * t o r e p r e s e n t s ' d o e s n o t e x i s t ' , b e c a u s e s o m e u s e r * s t i l l u s i n g J a v a 7 . * @ s e e < a h r e f = " h t t p s : / / o u r . d o m a i n / r e d m i n e / i s s u e / 1 2 3 4 5 " > r e l a t e d d i s c u s s i o n * / F o o g e t F o o ( ) ;
* @ p a r a m c o l u m n I n d e x * o n e - b a s e d v a l u e t o p o i n t s p e c i f i c c o l u m n , * z e r o t o s p e c i f y a l l c o l u m n s , o r * n e g a t i v e v a l u e t o u s e i n d e x f r o m r i g h t * ( e . g . - 1 i s r i g h t e s t c o l u m n ) * / C o l u m n s g e t C o l u m n s ( i n t c o l u m n I n d e x ) ;
what variables/classes/methods represent we prefer better naming instead 2. nullness of arguments and returned value we prefer JSR305 annotations (j a v a x . a n n o t a t i o n . @ N o n n u l l , @ N u l l a b l e and @ C h e c k F o r N u l l ) instead then IDE and static analysis tool will find problem based on annotations
negativeness of arguments and returned value we prefer JSR305 annotations (j a v a x . a n n o t a t i o n . @ N o n n e g a t i v e , and @ C h e c k F o r S i g n e d ) instead 2. API will close given @ C l o s e a b l e instance or not we prefer JSR305 annotations (j a v a x . a n n o t a t i o n . @ W i l l C l o s e , @ W i l l C l o s e W h e n C l o s e d and @ W i l l N o t C l o s e ) instead
tool to generate API document (HTML) from documentation comment 3. Documentation comment is comment which explains specification of API Javadoc javadoc
asap (refs: Teddy bear effect, Rubber duck debugging) 2. Use your future time to make new things, not to explain existing something 3. Stop remembering complex tacit knowledge, by stipulated document 4. Let API user to start develop even before you finish your implementation
HTML escape like & g t ; is necessary in text body. / * * : * < h 3 > I n v e r t i b i l i t y < / h 3 > * < p > T h e r e v e r s e o p e r a t i o n < b > m a y < / b > b e a s t r i c t < i > i n v e r s e < / i > . . . : * < p > G e t t i n g a c o n v e r t e r : * * < u l > * < l i > U s e a p r o v i d e d c o n v e r t e r i m p l e m e n t a t i o n , s u c h a s . . . : * / @ B e t a @ G w t C o m p a t i b l e p u b l i c a b s t r a c t c l a s s C o n v e r t e r < A , B > i m p l e m e n t s F u n c t i o n < A , B > { Visit to see full example. Guava on GitHub
parameter of documented method, constructor, class and interface. @ r e t u r n Describes the returned value from documented method. @ s e e Adds a reference including class, interface, method, field, and URL. See for detail. official document
r g e t t e x t } Adds hyperlink to text. It is useful to link to related class, interface, field or method. { @ c o d e t e x t } Wraps texts by <code> HTML tag. Inner text does not need HTML escape. { @ l i t e r a l t e x t } Applies HTML escape to text. See for detail. official document
eller86
inariku
ssakita
nobitabashi
ikki0006
kmotohas
sms_tech
pauli
goyoki
riyaamemiya
hiccupps
ianozsvald
aleyda
addyosmani
garrettdimon
chriscoyier
bluesmoon
lauravandoore
stephenakadiri
tonyrice
jacobian
konakalab
