Day 1: Javadoc

100daysOfProgrammingNotes (6 Part Series)

1 Intro
2 Day 1: Javadoc
… 2 more parts…
3 Day 2: Java Validation
4 Day 3: Auto Generate TOC Github Markdown
5 Day 4: Push existing project to existing Git repo
6 Day 5: CORS Setting for REST API in ReactJS

Intro

I have heard about Javadoc since the first time I touched Java like 5 years ago. But I realized that I still didn’t understand what Javadoc is until I wrote this note. At first I thought that Javadoc is a Java documentation that can be printed or exported as PDF. Yeah, a documentation about the program. Automatically generated. Well, I was not 100% wrong. But something that I missed was, how to create or leave a good Javadoc.

Usually a developer will leave comment and explain briefly about a line of code. Like in Java, we use “//” or “/** */” character to leave a comment. Well, that is not a Javadoc I found recently. It is beyond that. haha sorry for my inexperience 🙂

Javadoc

When we call method from other class, there will be a small pop up windows appears explaining what the method is about. That small pop up windows what they call JAVADOC~

I really didn’t understand until I found my own brief explanation about the method came out. And realized that is the right way to generate/ write comment to become a Javadoc.

How to write a good Javadoc

Writing documentation is important. Explain about the method/class or anything very briefly. So that, the next programmer who will read your code will understand what you are trying to write.

Above the method, start with /** to open a block comment section. This comment section can apply html and markdown tag. So make it pretty 😉

Always include @param, @return, @throws in the Javadocs. It’s important when calling this method, and have no idea how to use the method.

I learned that a @param has to be followed by explanation about the param itself. for example :
@param firstNumb the first number
@param secndNumb the second number

something like that. complete it with noun. for the detail of how to write a good Javadoc, please refer to reference below~

References

• Oracle

100daysOfProgrammingNotes (6 Part Series)

1 Intro
2 Day 1: Javadoc
… 2 more parts…
3 Day 2: Java Validation
4 Day 3: Auto Generate TOC Github Markdown
5 Day 4: Push existing project to existing Git repo
6 Day 5: CORS Setting for REST API in ReactJS

原文链接：Day 1: Javadoc