Re: Decouple Javadoc from Java
MRe wrote:
- 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).
There is a large amount of code which no amount of naming and structure
can render immediately evident. My longest comments are detailed
discussions into why I am using certain algorithms or pointedly failing
to adhere to a contract (e.g., ignoring part of a grammar for a file
format that is rather obtuse and nearly completely unused).
Comments are not for the 'you' that's writing the code, but the 'you'
that will be looking at the code five years later without seeing it
again. Can you really remember why you have the $ in your
"(?<![$:>])\\b\\w+(?=\\s*\\()" regex (the variable name is "globals_")
- 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.
There are certain statements that are a lot easier to express
colloquially than mathematically. In calculus, the idea of limits is
rather simple, colloquially (the points where the function would appear
to travel), but the mathematical definition is a tortuous ?-? form (see
end for full definition).
If you loosen yourself to merely the realm of computer programming, I
can tell you that there are some conditions that cannot be easily
verified, if at all, at runtime. For example, verifying some constraints
of AST trees (e.g., where nodes may or may not appear) at compile-time
would be difficult.
- 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
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.
If you step back and admit any form of documentation generation via
source comments (which would include tools like doxygen), I can honestly
say that there is little that despairs you more than finding absolutely
no documentation. ParseLine obviously parses a line, but what format
must the line be in? Is it a normal MIME header line, or some over
format of line? If it begins with a ., do I need to unquote it? Must I
include the CRLF at the end or not? What happens if the line is not in
the correct format?
You might object that it's named improperly, but even if I renamed it to
ParseXOVERLine, I still have several unanswered questions. All of this
is merely questions of interface; with well-written interface
documentation, I could easily answer this without having to go fishing
for implementation.
And there are times when you have to use interfaces without the actual
implementations to back you up.
- 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.
On large projects, I think that having copious documentation inline with
code is going to compel people more to remember to update documentation,
versus it being in separate files.
- Also, I agree that programmers should NOT have to be literate in
some natural language. They're programmers, literate in the language
of programming! To expect a programmer to be a wordsmith.. Aaah! No!
The essence of language is taking a group of discrete elements with
ambiguous meanings by themselves and combining them with standardized
structural elements to provide for a practically limitless range of
meanings and possibilities. How different is that from programming?
Language is also a vehicle for communication of ideas; programmers will
most likely have to tell others about what they're doing more often than
having to mathematically defend the correctness of their code. With that
in mind, it would make more sense for programmers to be required to take
technical writing courses than it would for them to learn advanced
mathematics.
No one's asking programmers to be the next Shakespeare or Victor Hugo,
but at least taking some time to learn how to write sensibly would not
be too hard to ask, would it? Oh yes, and focus on correct orthography
and grammar would be much appreciated.
P.S. Mathematical description of an ?-? limit:
A function f(x) has a limit L as x approaches c iff for all real ? > 0,
there exists a ? > 0 such that 0 < |x - c| < ? implies |f(x) - L| < ?,
for all x in an open interval containing c.
--
Beware of bugs in the above code; I have only proved it correct, not
tried it. -- Donald E. Knuth