Re: a criticism of java


ricky.clarkson@xxxxxxxxx wrote:
> > The throws clause is part of the language and not an effective tool for
> > documenting the method.
>
> Am I to take this to mean that documentation needs to duplicate the
> source code?

That wasn't what I meant, but what the advice you wrote is lucid and
wise.

Personally, I tend to write reams of notes for a method , and write it
outside the code, because it'd just make the code unreadable. I
wouldn't call it documentation since it's more notes to self, and I
wouldn't expect anybody else to read it until I tidy it up. It's more
whitebox notes.

I do write brief 'whitebox' notes in the code within the method too

But yes. Blackbox notes, just what goes in and out of the method, that
can be included in the code , and is a commentary on the method header.

I'm glad you posted this, because, although I wasn't disagreeing with
it, it has clarified things for me.

Blackbox documentation, is a commentary on the method header.
Thus, you are wise in - it seems to me - saying that the blackbox
documentation shouldn't duplicate what is written in the method header.
Like variable types.
And that strict typing helps document the code too, (as well as
preventing errors)


I was really only referring to after the throws clause. But I wasn't
even being that radical. No doubt that what is after the throws clause
is useful for documenting the method, but it shouldn't be adapted to
provide documentation for the method. I was debating with a guy that
appeared to me to not agree with unchecked exceptions, so he thought
that all exceptions should be checked, and thus would have no qualms in
listing all exceptions, including 'out of memory' exception and others,
on the end of a throws clause.
Declaring checked exceptions has ramifications. It's not necessarily
that I disagree with all checked exceptions. But those examples I gave
are from my short experiences with java, and those method shouldn't
have been throwing checked exceptions.




>
> /**
> @param values an array of type int passed in using the varargs
> syntax.
> @return an int which is one of the passed in values.
> */
> int giveOneBackAtRandom(int... values)
> {
> return values[(int)(Math.random()*values.length)];
> }
>
> It seems to me that the 'int' nature of the parameters and return type
> is better expressed in the language. Now suppose I change this method
> to use doubles:
>
>
> /**
> @param values an array of type int passed in using the varargs
> syntax.
> @return an int which is one of the passed in values.
> */
> double giveOneBackAtRandom(double... values)
> {
> return values[(int)(Math.random()*values.length)];
> }
>
> I've got a mismatch between comment and code, caused by the comment
> duplicating the code. Here is a better comment:
>
> /**
> @return one of the parameters, chosen at random.
> */
>
> Much more concise, and as it happens, it's more useful too, because
> earlier I was concentrating on filling in @param and @return, getting
> the return type right, etc., and completely forgot to mention
> randomness.

you speak wisely

> > Efforts are being made in academic circles to use mathematical symbols
> > to document programs. e.g. to say that an array is sorted.
>
> Why not use a SortedSet, or a custom implementation that wraps an array
> or always making sure it is sorted? Then it will be blindingly obvious
> that it's sorted, because it will be of type SortedArray or something.

That'd probably be better given the goal of sorting the array using the
java language.

But that'd just be as a demonstration for what can be done. I'm not an
academic, but i'm aware that there is work by Professor Bornat to prove
the correctness of programs using Hoare Logic. So no doubt it gets mroe
sophisticated than proving the correctness of a method to sort an
array.


> The code should be as expressive as is practical, to enforce contracts.
> That's the great advantage of static typing, we can have contracts.
> In dynamically-typed languages, we can do stuff like:
>
> /*
> Adds the specified item to the specified list
> */
> function push(var list,var item)
> {
> list.add(item);
> }
>
> Then someone comes along and types the parameters in the wrong order,
> and ends up adding a list to a string instead of a string to a list.
> The runtime doesn't notice. This is because the contract is not
> expressed in code, it is expressed in documentation. Documentation
> isn't as strict as a static-type-checking language:

indeed. I wouldn't make documentation a substitute for code or code a
substitute for documentation. But sometimes they complement one another
as you demonstrate. And the method header forms part of the
documentation, or the subject, of the documentation's commentary.


> public static <T> void push(final List<T> list,final T item)
> {
> list.add(item);
> }
>
> This not only catches the above bug, but prevents some other bugs, like
> adding a Banana to a List<String>, for example. A real case I've seen
> recently is a new programmer mixing up Strings and JTextFields, and
> unfortunately using 1.4.
>
> So if you need to specify part of the contract in documentation, you're
> probably fighting the language or lamenting something you wish it had.

Perhaps documentation within the code shouldn't duplicate what is in
the method header.
But I think that the chap I was discussing/debating with was lamenting
that unchecked exceptions weren't actually checked, and he might have
wanted to declare all of those.

I would say that they certainily shouldn't be written in the method
header. (java has unchecked exceptions - I believe with good reason).

He may write them in his documentation (though I wouldn't do that in
the 'in code' blackbox documentation - it wouldn't be brief enough to
be there).
It'd be in the exhaustive whitebox documentation that is mostly my
thoughts gathered together in a structured manner as I program.


And, my beef was with certain methods throwing checked exceptions when
I felt they should've been throwing unchecked exceptions. Thus, I
didn't want to be declaring them after the throws. If I were to
document that they are thrown, I'd write outside the source file, and
certainly not write them in the code. There are so many unchecked
exceptions.
I would not adapt the throws clause to provide documentation to a
checked exceptions that should really be unchecked.

Hence In those instances, I support not declaring them, by saying.

public int methodQ(String a) throws Exception
{
}



I would also manually throw the unchecked IllegalArgumentException,
and I might declare that, since I think that exception is very relevant
as a reminder to the programmer.


By the way. I see your understanding is lucid. Are you a teacher?
Do you recommend any particular book or sources of info for improving
my programming?

Where I see wisdom, I take advice. I see wisdom!

.

Relevant Pages

  • Re: CLOS and C++
    ... > relative percentage of needing to know the exceptions a given method can raise ... >> with the information provided by the mandatory type declarations. ... javadoc comments and put it into the class file and then change the ... attach the documentation directly to the elements its documenting so ...
    (comp.lang.lisp)
  • Re: SqlConnection.Open() Which ErrorCodes
    ... exceptions is that they are often too generic and the ... Hitchhiker's Guide to Visual Studio and SQL Server ... the documentation in the .NET Framework Help for these classes: ...
    (microsoft.public.dotnet.framework.adonet)
  • Re: Problems Handling Errors Correctly
    ... But as with your observation about the .NET Framework itself, to some extent this is a consequence of the sheer size of the Framework. ... One hopes that over time, the documentation will get filled in, but it's not hard to see why some things may have been considered lower priority and receive a basic "template" documentation rather than a fully useful description. ... the docs include a section immediately after the "Return Value" section enumerating possible exceptions. ... If it's not the case, or it's incomplete, or it leaves out exceptions that could be thrown my methods called from the method, that would really be a drag. ...
    (microsoft.public.dotnet.languages.csharp)
  • Re: O/T: Quote Of THe Day
    ... complexities of current life are completely different now compared to ... programs of proposed protocols, and documentation, documentation, ... forms of legalese with exceptions and exceptions to the exceptions. ... So let us do away with the HIPAA forms and everything analogous, ...
    (rec.woodworking)
  • Re: access(FULLPATH, xxx);
    ... with "trial& error" to just silence the compiler. ... void *foo); ... given that the language in the specification _was_ abiguous and both ... documentation was paramount. ...
    (freebsd-questions)