UNDERSTAND COMMENT AND JAVADOC IN 10 MINS

UNDERSTAND COMMENT AND JAVADOC IN 10 MINS

4ccf6c02807d06f043a71435c48ce86a?s=128

Kengo TODA

April 13, 2016
Tweet

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