DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Refcards Trend Reports
Events Video Library
Over 2 million developers have joined DZone. Join Today! Thanks for visiting DZone today,
Edit Profile Manage Email Subscriptions Moderation Admin Console How to Post to DZone Article Submission Guidelines
View Profile
Sign Out
Refcards
Trend Reports
Events
View Events Video Library
Zones
Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks

Mobile Database Essentials: Assess data needs, storage requirements, and more when leveraging databases for cloud and edge applications.

Full-Stack Observability Essentials: Explore the fundamentals of system-wide observability and key components of the OpenTelemetry standard.

Monitoring and Observability for LLMs: Datadog and Google Cloud discuss how to achieve optimal AI model performance.

Automated Testing: The latest on architecture, TDD, and the benefits of AI and low-code tools.

Related

  • Low-Code Approach to Application Development
  • What Is a Modern Developer?
  • Atomic Habits and Software Engineering: Unlocking Career Success
  • Unlocking Game Development: A Review of ‘Learning C# By Developing Games With Unity'

Trending

  • .NET Performance Optimization Techniques for Expert Developers
  • Helm Dry Run: Guide and Best Practices
  • How To Aim for High GC Throughput
  • Protect Your Keys: Lessons from the Azure Key Breach
  1. DZone
  2. Coding
  3. Java
  4. JavaDoc: The Unloved Child. A Pragmatic Approach

JavaDoc: The Unloved Child. A Pragmatic Approach

Markus Eisele user avatar by
Markus Eisele
·
Feb. 18, 11 · Interview
Like (0)
Save
Tweet
Share
8.19K Views

Join the DZone community and get the full member experience.

Join For Free

Project documentation is an important but awkward thing to do. Same is true for JavaDoc. The few special comments in the Java source code that are delimited by /** ... */. This short post presents a very pragmatic approach to JavaDoc and outlines the general best practices for successful sourcecode documentation.

Why you should care!

Look at the NetBeans screenshot from the right. This is the tooltip you get, when trying to use the method. And now? What happens? Why? For what? How does this thing behave? Do you know what to do, if you see a getInstance() method?
The second screenshot gives you a more detailed idea about what you can achieve with writing some JavaDoc comments. And it applies to nearly any situation. If you are writing any kind of Java program you should keep in mind, that others probably want to use it's public API or need to use your implementation. This is not only true for framework developers but for anybody working within a team. Even if we are talking about component boundaries or utility classes. A class without documentation is trivial or worthless.

Hey: I am a programmer not a writer!
In theory, the general idea of commenting code sounds like a worthy one: Offer the reader detail, an explanation of what's going on. What could be more helpful than being helpful?
To make it short. I am not proposing to write too much beside the actual code. But that's exactly the problem. Beside the fact, that there are a couple of JavaDoc tags you could use it's also mostly up to you how much and what you write. The basic rule of thumb is:
Comments should say something code does not and cannot say.
(Source: 97 Things Every Programmer Should Know)
Does this help? Partly. This rule needs some interpretation. If you don't have source.jars at hand you probably don't have any code at all to look at. So: The less open the source is, the more extensive the comments should be. The second idea here is to look at your stakeholders. Who is the one intended to read the documentation? I don't like the idea to talk about skills here. My favorite is to classify the APIs into abstraction level. The higher the abstraction level, the more general and easier readable texts should be there. If you have a lower abstraction level, the texts could be more technical and probably less readable in terms of writing style. But, it's always good to remember the reworked old adage as a rule to keep in mind:
If it was hard to write, it should be EASY to read!

Ok: Tell me, which are the important parts?
Now you know, how and when to document your sources. What does this mean in practice?
If you refer to the Java SE 6 JavaDoc documentation you have 19 tags which you could use to. Here are the usage guidelines I propose for your next project:

1) Introduce a class header with a single line of documentation ("First Sentence") and an @author tag at a minimum.
2) Add as many documentation up the hierarchy as possible. Use {@inheritDoc} down the hierarchy.
3) Document all public methods except getters and setters with at last a single line and add @throws and @return. @params only if they are not obvious.
4) Use @link as internal reference and @see to add references to external resources.
5) Javadocs should get peer-reviewed, just like code.

Optional but possible needed:
- Introduce a meaningful file comments if needed (e.g. OSS or Company Copyright). Skip it, if not!
- If you are developing versions you should make broad use of the @deprecated tag where applicable.

That's all. Nothing more. Nothing less.
What are your best practices in projects? Let me know. Comments and other ideas are welcome!

Read more
JavaDoc Overview (Java SE 6)
How to Write Doc Comments for the Javadoc Tool
JavaDoc Tags
JLS Documentation Comments (first Edition)

 

From http://blog.eisele.net/2011/02/javadoc-unloved-child-pragmatic.html

Javadoc code style

Opinions expressed by DZone contributors are their own.

Related

  • Low-Code Approach to Application Development
  • What Is a Modern Developer?
  • Atomic Habits and Software Engineering: Unlocking Career Success
  • Unlocking Game Development: A Review of ‘Learning C# By Developing Games With Unity'

Comments

Partner Resources

X

ABOUT US

  • About DZone
  • Send feedback
  • Careers
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 3343 Perimeter Hill Drive
  • Suite 100
  • Nashville, TN 37211
  • support@dzone.com

Let's be friends: