Re: Decouple Javadoc from Java
MRe wrote:
Well, philosophically, I'm sure there's plenty here to argue about;
and enough opinions to make it moot (bar, useful for starting
discussions).. so, for what it's worth, here's my humble opinion:
- Javadoc clutters Java code! When I write Javadocs, I'll typically
end up with, like 80% of my Java code containing Javadoc (did you see
Good work! Too many people underdocument their code.
that? 80% of my Java source file is not Java :). So when I'm there to
write Java, as a Java programmer, why am I sifting through all this
Javadoc nonsense.
To benefit those who are stuck with using your code.
- Careful use of naming and structure should make code meaning self
evident. If I feel a need to add source comments, it means my code is
wrong (overly complicated).
Javadoc is not for people who are reading the code, as was pointed out upthread.
- Javadoc's demographic should be people who are not going to look
at code; 'external use', not 'internal workings.' I am making this
That is correct.
claim based on the Javadoc output, which offers nothing to developers
about understanding internals. Therefore, it shouldn't have to be
constantly updated to code changes, it should be abstract enough to
If you write your doc comments correctly and your interface is stable, then
you don't need to "constantly update" your doc comments.
survive such things. If a Javadoc needs to be changed often, then
clearly nobody knows what the program is suppose to be doing.
Agreed, once the initial development epicycles have settled down.
- Java is a language that can be reasoned about mathematically (erm,
almost); Javadoc is definitely not. Describing an unambiguous language
with an ambiguous one! Why? The only comments in Java should be JML or
similar; i.e., post/pre-conditions, invariants, assertions.
Again, that only helps people who read the code. Javadoc is for people who
need to use the code.
- Javadoc cannot be proven---it is like the stopped watch versus the
lose-a-minute-every-5 watch. The stopped watch might look worse, but
it's correct twice a day, Ha!---Hmmm, what I mean is, you can never be
Irrelevant. Javadoc is literature, not software.
sure Javadoc is correct. I only ever read it when all else fails,
typically resulting in me being more confused, deleting all the
comments, and then without the clutter, finally being able to
understand the code.
Then the Javadoc comments were poorly written. And by deleting the doc
comments, you have ruined the code for everyone except the programmer.
- I'd say it's na?ve to think the type of person who would not keep
their Javadoc in check with their code when it's in a separate file,
is going to do it when it's inline. OK, maybe they're more likely too,
but I wouldn't count on it.
If you're a professional, you'll keep the comments up to date no matter which
way they're stored. If you're not a professional, what the heck are you doing
here?
The psychological advantages of Javadocs being with the code have more to do
with making the code match the comments than vice versa.
- If Javadoc could be decoupled, then it would be possible for
several versions: one for user, one for developer, and one for Lojban.
Javadocs are for those who program clients of the code, less so for those
maintain the code. For the maintainer, the Javadocs tell one what the code is
supposed to do - they're better for instructing the programmer than reflecting
the mess they make of it.
What the heck is a Lojban?
- Also, I agree that programmers should NOT have to be literate in
some natural language. They're programmers, literate in the language
Nonsense. Utter trash.
of programming! To expect a programmer to be a wordsmith.. Aaah! No!
We're not talking about being a "wordsmith". We're talking about professional
competence at clear communication.
It boggles the mind.
Yours, maybe.
Is it possible for a computer game to have no
graphical element? No? Does that mean a games programmer must be a
graphics artist?
Yes. At least, someone on that team had better be.
They're two completely different languages, reasoned
about in different parts of the brain (I'm guessing, but it sounds
like it might be true :) On a side note; I did so bad in my Human
Language Technologies college exam---I wasted most if thanks to my
sucky English. Build a phase structure tree, no problem.. wait a
minute, what do you mean I have to know with which part of speech a
word belongs. Man, I fail words..
That's got nothing to do with the type of language competence needed to write
good Javadocs.
If you can't explain what the code is supposed to do, then you don't know what
the code is supposed to do.
Anyway, end of opinion. I guess the answer to my original question is
no. The Javadoc compiler in its current state does not have the
ability to allow a decoupling of Javadoc and Java.
Quite aside from the philosophical points, whether one agrees or disagrees
with either of us, the technical nature of the Javadoc tool requires the
comments to be associated with, if not necessarily within the source code.
The Javadoc tool uses semantic information from the source and antecedent
bytecode to generate its output. In its current implementation, that does
require the doc comments to be in the source.
As strongly as you feel about it, why not start a project to create an
alternative doc comment tool?
--
Lew