Re: Decouple Javadoc from Java
...Java comments is definitely an important thing. But Javadoc, for a
user, shouldn't be the responsibility of a programmer.
Of course it should, or an analyst or architect - someone who understands
code. Ideally, Javadoc should be written with the interface definition and
used by the implementer to guide their coding.
Fine, let the programmer write the Javadoc; just not alongside the
Javadoc with the interface definition? YES! That would be perfect, but
only if the interface was separate to the implementation (like C/C++).
It's a best practice in Java to write interfaces and implementing classes, and
for client code to declare referencing variables as the interface type.
Because Javadoc comments are embedded in the code, and the Javadoc tool can
follow inheritance, you can place the Javadoc comments only in the interfaces
and the implementing classes will inherit them (for public methods).
However, my mother raised me to sit in dark rooms, but for the glow of
a blank white page on my screen, gradually getting darker as that page
fills with code. I'm a programmer, I write programs. There is of
course the necessity that I write comments explaining the intricate
details of my code to other programmers. But Javadoc, written for a
Javadoc users are programmers who write code.
user who just cares about the interface is, I believe, completely
Written for the programmer who cares about the parts of the code they will
directly use in their own code.
different. My main directive is to write code. When it's necessary, I
also write comments. But it's not my responsibility to write the
Yes, it is. How can anyone be expected to write programs using undocumented
code? Who knows the code better than the programmers? Who else is better
qualified to write the documentation?
Regardless of whether the programmer is capable of actually writing
the Javadoc is one thing, but Javadoc is not code, it's not code
comments, it doesn't belong where they exist.
Javadoc is necessary for people who are writing code using the documented
code. It is a convenience that the doc comments are in the source itself. It
increases the power of the Javadoc tool to follow inheritance and method
signatures, etc. It increases the documentation for people who are reading
the source code. It increases the documentation for people who are using the
code in their own programs. It reflects the best practice that
CODE MUST BE COMMENTED
by non-trivial comments that explain the purpose and usage of the code.
I disagree with that completely. A programmer needs to be able to express
their thoughts clearly in a natural language. Too bad for you if you can't;
it's a serious disadvantage.
What if you're an employer of a company that speaks natural language
A, and you get your hands on the greatest programmer who ever has or
will exist and who will work for beans, except they speak natural
language B? Does that mean this person is a useless programmer? No,
Yes, actually, to those programming with Natural Language A. Experience for
many programming shops has proven that language barriers are a severe
impediment to effective software development.
what you want is someone else who understands language B, and who will
translate it into language A.
I work on a large programming project in the U.S. with people from many parts
of the world. Several people there speak, for example, Mandarin Chinese far
more fluently than they speak English. Talking with others there who speak
Chinese, they frequently will eschew English for the sake of efficient
communication. However, not one person hired on that project speaks only
Chinese, even though there are at least a dozen people there who could
translate anything being said to them in English. The employer is not
prejudiced - it's just not practical to hire even the best programmer who
cannot speak English.
Bilingual programmers command big extra compensation because they don't need
to have Natural Language A translated for them.