UNDERSTAND COMMENT AND JAVADOC IN 10 MINS

Transcript

1. UNDERSTAND COMMENT AND JAVADOC IN 10 MINS Kengo TODA
2. AGENDA 1. WHY COMMENT? 2. WHAT IS JAVADOC? 3. WHEN JAVADOC? 4. HOW TO JAVADOC?
3. WHY COMMENT? To tell WHY!
4. WHY COMMENT? By writing comment, you can tell something like: 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
5. WHY WE HAVE SO UNINTUITIVE CODE AT HERE M y 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 ; }
6. WHY WE CANNOT USE BEST PRACTICE AT HERE / * * * 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 ( ) ;
7. METADATA OF ARGUMENTS, RETURNED VALUE AND EXCEPTIONS / * * * @ 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 ) ;
8. ALTERNATIVES Comment is not the way to explain followings: 1. 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
9. ALTERNATIVES Comment is not the way to explain followings: 1. 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
10. HERE WE HAVE A SIMPLE RULE When you worry that comment is not the best way, remember: Comment is to explain WHY, not WHAT. Javadoc is API documentation, to explain API spec.
11. WHAT IS JAVADOC? It is documentation comment for Java.
12. WHAT IS JAVADOC? 1. is documentation comment 2. is a tool to generate API document (HTML) from documentation comment 3. Documentation comment is comment which explains specification of API Javadoc javadoc
13. FORMAT OF JAVADOC / * * ← w e n e e d t w o a s t e r i s k s t o s t a r t j a v a d o c . * * W e c a n e x p l a i n s p e c o f A P I h e r e f r e e l y . * /
14. WHEN JAVADOC? Before code. If time permits, doc-first development is the best.
15. BENEFITS OF DOC-FIRST DEVELOPMENT 1. Find unclear thing in API 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
16. HOW TO JAVADOC? It’s simple HTML, and from Java9. You can also use block tag like @ s e e , and inline tag like { @ c o d e . . . } . will be HTML5
17. HOW TO JAVADOC? Just write HTML like below. Note that 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
18. BASIC BLOCK-TAGS @ p a r a m Describes the 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
19. BASIC INLINE-TAGS { @ l i n k t a 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
20. THANK YOU! . Please fork this slide at Gist