Understand comment and javadoc in 5mins https://slideck.io/gist.github.com/KengoTODA/daa8a35680752e75f1fe/index.md

index.md

Understand comment and javadoc in 10 mins

Kengo TODA

---

Agenda

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

---

WHY COMMENT?

To tell WHY!

---

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

---

Why we have so unintuitive code at here

MyDate(int year, int month, int day) {
  // given parameter is one-based, but we need zero-based value
  // to play with legacy systems and Java API
  this.month = month - 1;
}

---

Why we cannot use best practice at here

/**
 * This method still returns null (not empty Optional)
 * to represents 'does not exist', because some user
 * still using Java7.
 * @see <a href="https://our.domain/redmine/issue/12345">related discussion and its result</a>
 */
Foo getFoo();

---

Metadata of arguments, returned value and exceptions

/**
 * @param columnIndex
 *             one-based value to point specific column, 
 *             zero to specify all columns, or
 *             negative value to use index from right
 *             (e.g. -1 is rightest column)
 */
Columns getColumns(int columnIndex);

---

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 (javax.annotation.@Nonnull, @Nullable and @CheckForNull) instead
   • then IDE and static analysis tool will find problem based on annotations

---

Alternatives

Comment is not the way to explain followings:

3. negativeness of arguments and returned value
   • we prefer JSR305 annotations (javax.annotation.@Nonnegative, and @CheckForSigned) instead
4. API will close given @Closeable instance or not
   • we prefer JSR305 annotations (javax.annotation.@WillClose, @WillCloseWhenClosed and @WillNotClose) instead

---

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.

---

What is Javadoc?

It is documentation comment for Java.

---

What is Javadoc?

1. Javadoc is documentation comment
2. javadoc is a tool to generate API document (HTML) from documentation comment
3. Documentation comment is comment which explains specification of API

---

Format of Javadoc

/** ← we need two asterisks to start javadoc.
 *
 * We can explain spec of API here freely.
 */

---

When javadoc?

Before code.

If time permits, doc-first development is the best.

---

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

---

How to javadoc?

It's simple HTML, and will be HTML5 from Java9. You can also use block tag like @see, and inline tag like {@code ...}.

---

How to javadoc?

Just write HTML like below. Note that HTML escape like > is necessary in text body.

/**
   :
 * <h3>Invertibility</h3>
 * <p>The reverse operation <b>may</b> be a strict <i>inverse</i> ...
   :
 * <p>Getting a converter:
 *
 * <ul>
 * <li>Use a provided converter implementation, such as ...
   :
 */
@Beta
@GwtCompatible
public abstract class Converter<A, B> implements Function<A, B> {

Visit Guava on GitHub to see full example.

---

Basic Block-Tags

• @param Describes the parameter of documented method, constructor, class and interface.
• @return Describes the returned value from documented method.
• @see Adds a reference including class, interface, method, field, and URL.

See official document for detail.

---

Basic Inline-Tags

• {@link target text} Adds hyperlink to text. It is useful to link to related class, interface, field or method.
• {@code text} Wraps texts by <code> HTML tag. Inner text does not need HTML escape.
• {@literal text} Applies HTML escape to text.

See official document for detail.

---

Thank you!

Please fork this slide at Gist.