JavaDoc or Java Source?

One of my Twitter heroes asked a question this week:

What if the code in our most used OSS Java had no JavaDoc? Would we still be as productive and find it as useful?

I'll be frank, most of what I look for in JavaDoc I don't find. The documentation mostly describes either what is obvious due to great naming or is so esoteric that it doesn't help.

An example.

I'm working on updating a group of services from Spring Boot 1.x to 2.x. I've been trying to understand the mapping of Thymeleaf classes from 2.x to 3.x. JavaDoc has not helped at all with that. How can it?

I argue naming is far more important that documentation. Intuitive names tell EVERYONE what the thing is doing. No further explanation needed.

Another example.

I'm trying out Kotlin, building a Spring Boot API with it. Here's something I was just looking at:

public annotation class PublishedApi

An annotation provided by Kotlin that publicizes a previously internal API. Not sure documentation is needed here. Let's look.

 * When applied to a class or a member with internal visibility allows to use it from public inline functions and
 * makes it effectively public.

Hmm, yeah, that's what I took away from the name. Now, there are some details that spell out some interoperability when additional logic is used that is not also public, which can be helpful. BUT, if you have spent moderate time with the language, you know this.

JavaDoc is nice to have, especially when it is 4pm and your brain is fried on something you've been stuck on since last week. I'll give it that.

However, I don't think it should be necessary if naming is executed well. Difficult to do, but necessary to strive for.

Hit me up on Twitter to tell me how I'm wrong and thanks for reading!

Comments powered by Talkyard.