Hacker News Reader

Comment by foobazgt | Hacker News Reader

The author rants about Java a lot, when they admit they've never even used it. It shows. People view documentation in their IDEs. Generated javadoc is almost not a thing nowadays. I suspect this is the same in similarly statically typed languages with good IDE support.

View on HN

First time I saw an experienced Java programmer at work was a revelation. One hand on the keyboard, one hand on the mouse. Hardly ever actually typed anything. Line width set to 200 characters. Cranking out boilerplate, 5 lines with a single mouse click. Measured in lines of code, his productivity was off the charts.

And still, I switched to C# now and I have to tell, my overall java productivity was massively better. Better tooling, better code analysis, better literally everything.

IDEs will show you the docs for whatever method you're using… but their support for navigation or exploration tends to be somewhere between "absent" and "severely lacking".

Do you have specific examples in mind?

Navigation is quite good (at least in Visual Studio C#). You can see usages and go up and down the class hierarchy quite easily.

Exploration, though, not so much. But you have is "object." and then read the methods and properties. It's not awful, but if you don't know the object first you can't do it.

I still use javadoc a lot. I was shocked to see the author complain about it. I have always found javadoc to be one of the best language docs to date. I find myself missing it constantly when I am using other less documented languages and libraries. It is well structured and exhaustive, the only confusing parts of it are where the actual underlying class is poorly structured.

I would highly suggest using javadoc before something like SO when you are confused about how to use a class. The vast majority of SO's java help is frozen in time due to SO's 'no duplicate questions' policy. Java has improved a lot since java 7.

Java IDEs still rely on Javadoc behind the scene in my knowledge, so you might be correct that some UIs have been replaced by IDEs but its basic format never changed. Also such documentations do not account for introductional or topical contents that can't be reached from a source code.

Right, I was careful to say "generated javadoc", but that nuance might not have been obvious. The author's point is not about the syntax you use to write documentation, it's about the experience you have consuming it. (And FWIW, Java 23 supports Markdown comments[0]).

Re: "introductional/topical contents", this is what package-info.java files are for.

0) https://openjdk.org/jeps/467

Do you look up symbols in the IDE? What about finding all symbols in a package? I use inline IDE documentation a lot but still also use the online or offline copy of the HTML reference manual.

> Do you look up symbols in the IDE?

Yes.

> What about finding all symbols in a package?

I do not know what exactly you mean here, but I look for stuff like "all methods" or "implementations" in IDE.

> I use inline IDE documentation a lot but still also use the online or offline copy of the HTML reference manual.

I literally never ever use offline copy of the HTML manual nor need a need for it. I use online copy when google lands me there - but typically I then find the same thing in IDE, because then I see also a source code and have generally great experience.

To me, having to read manual online is a fail of documentation.

Reply on news.ycombinator.com