UNDERSTAND COMMENT AND JAVADOC IN 10 MINS

UNDERSTAND
COMMENT AND
JAVADOC IN 10 MINS
Kengo TODA

View Slide

AGENDA
1. WHY COMMENT?
2. WHAT IS JAVADOC?
3. WHEN JAVADOC?
4. HOW TO JAVADOC?

View Slide

WHY COMMENT?
To tell WHY!

View Slide

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

View Slide

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
;
}

View Slide

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
(
)
;

View Slide

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
)
;

View Slide

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

View Slide

ALTERNATIVES
Comment is not the way to explain followings:
1. negativeness of arguments and returned value
(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
(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

View Slide

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.

View Slide

WHAT IS JAVADOC?
It is documentation comment for Java.

View Slide

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

View Slide

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
.
*
/

View Slide

WHEN JAVADOC?
Before code.
If time permits, doc-first development is the best.

View Slide

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

View Slide

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

View Slide

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
>
* 
T
h
e r
e
v
e
r
s
e o
p
e
r
a
t
i
o
n 
m
a
y
 b
e a s
t
r
i
c
t 
i
n
v
e
r
s
e
 .
.
.
:
* 
G
e
t
t
i
n
g a c
o
n
v
e
r
t
e
r
:
*
* 
* <
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

View Slide

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

View Slide

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 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

View Slide

THANK YOU!
.
Please fork this slide at Gist

View Slide

UNDERSTAND COMMENT AND JAVADOC IN 10 MINS

UNDERSTAND COMMENT AND JAVADOC IN 10 MINS

Kengo TODA

More Decks by Kengo TODA

Other Decks in Technology

Featured

Transcript