«

my Java tutorial

http://xahlee.org/java-a-day/java.html

is now available for download for offline reading.
Download link at the bottom.

Xah
∑ http://xahlee.org/

☄

Xah wrote:
> my Java tutorial
> is now available for download for offline reading.
> Download link at the bottom.

Doesn't look terribly good as a tutorial.

My nits:
1. References either Java 1.4 or Java 5 documentation, the former of
which is EOL, and the latter of which is beginning the EOL process.
2. No explanation of how to use newer Java features, such as generics,
annotations, or enums. Doesn't even use them in earlier examples.
3. Several typos litter the place.
4. Sacrifices correctness for approachability. Specific examples:
4a. "lines enclosed between '/*' and '*/' are ignored." Lexically, those
indicate the start and close of a comment token, so that it's not
"lines" that are ignored, but "characters" (which is even a bit
imprecise, since it's actually collecting output from the Unicode
preprocessing).
4b. "special syntaxt [sic] to create jagged array in one shot." The
syntax isn't special, it's a standard array creation and assignment
expression.
4c. "constructer (often spelled constructor)" Actually, the JLS defines
it as "constructor," along with my ISO C++ spec, and the python specs.
"Constructor" is the accepted spelling, whereas "constructer" is a
misspelling not even in the OED.
4d. "For example, if your file name is 'MyMainClass.java', then one of
your class [sic] must be named 'MyMainClass'." No, it doesn't. The
correct sentence is that "..., then a public top-level class must have
the name 'MyMainClass'."
5. Violation of several accepted conventions.
6. Pointing people to bad practices, such as shoving a static method
into a non-static context.

I'll stick with <http://java.sun.com/docs/books/tutorial/index.html>,
thank you very much.
--
Beware of bugs in the above code; I have only proved it correct, not
tried it. -- Donald E. Knuth

On Jun 30, 10:11 am, Joshua Cranmer <Pidgeo...@verizon.invalid> wrote:
> Xah wrote:
> > my Java tutorial
> > is now available for download for offline reading.
> > Download link at the bottom.
>
> Doesn't look terribly good as a tutorial.

Thanks for your comments.

> My nits:
> 1. References either Java 1.4 or Java 5 documentation, the former of
> which is EOL, and the latter of which is beginning the EOL process.

True. Maybe i'll update later if i get to learn what's new java 6 or
some new features introduced in java 5.

> 2. No explanation of how to use newer Java features, such as generics,
> annotations, or enums. Doesn't even use them in earlier examples.

These are kinda intentionally left out, because i feel they are not
that practical or related to basic general programing concepts.

> 3. Several typos litter the place.

Humm... not sure which you refer to. Some, as you mentioned, are just
unconventional usages that may seem odd to native English speakers but
more logical and easy reading to international readers.

> 4. Sacrifices correctness for approachability. Specific examples:
> 4a. "lines enclosed between '/*' and '*/' are ignored." Lexically, those
> indicate the start and close of a comment token, so that it's not
> "lines" that are ignored, but "characters" (which is even a bit
> imprecise, since it's actually collecting output from the Unicode
> preprocessing).

> 4b. "special syntaxt [sic] to create jagged array in one shot." The
> syntax isn't special, it's a standard array creation and assignment
> expression.

it is rather ad hoc when one considers the generality or regularity of
the syntax with respect to syntax design among computer languages.

> 4c. "constructer (often spelled constructor)" Actually, the JLS defines
> it as "constructor," along with my ISO C++ spec, and the python specs.
> "Constructor" is the accepted spelling, whereas "constructer" is a
> misspelling not even in the OED.

> 4d. "For example, if your file name is 'MyMainClass.java', then one of
> your class [sic] must be named 'MyMainClass'." No, it doesn't. The
> correct sentence is that "..., then a public top-level class must have
> the name 'MyMainClass'."

Yes, practical and basic programing concepts are emphasized in this
tutorial. I might change the spelling of “constructer� to
“constructor� as you suggest. Note however, that “constructer� is more
logical and a standand alternative, shown in most if not all English
dictionaries. (you didn't find it OED?? i don't have access to Oxford
Eng Dict atm but i doubt its not in it)

> 5. Violation of several accepted conventions.

You mean English writing conventions or some java programing
conventions? Again, some of these are intentional. The alternative
form i used usually is based on simplicy or logical consistancy.

> 6. Pointing people to bad practices, such as shoving a static method
> into a non-static context.

Again, basic, practical, to-to-point programing is emphasized. I
discussed in the intro a bit, many things typical in Java tutorial
such as tips on current Software Engineering issues, or discussing the
lang from computer science point of view such as stacks, memory
allocation, etc, are not used here. (personally i find them
detrimental)

Xah
∑ http://xahlee.org/

☄

> I'll stick with <http://java.sun.com/docs/books/tutorial/index.html>,
> thank you very much.
> --
> Beware of bugs in the above code; I have only proved it correct, not
> tried it. -- Donald E. Knuth

Xah wrote:

Joshua Cranmer wrote:
> > My nits:
> > 1. References either Java 1.4 or Java 5 documentation, the former of
> > which is EOL, and the latter of which is beginning the EOL process.

Xah wrote:
> True. Maybe i'll [sic] update later if i [sic] get to learn what's new java [sic] 6 or
> some new features introduced in java [sic] 5.

As Joshua pointed out, Java 5 is already in End-of-Life. Just about
when were you planning on learning its "new" features?

Joshua:
> > 2. No explanation of how to use newer Java features, such as generics,
> > annotations, or enums. Doesn't even use them in earlier examples.

Xah:
> These are kinda intentionally left out, because i [sic] feel they are not
> that practical or related to basic general programing concepts.

Shocking. These are major improvements to the language which are
intensely practical and very much related to general programming
concepts, like, for example, type safety. Furthermore, the additions
to the API were significant and also intensely practical.

That you consider them otherwise undermines your credibility to offer
tutorials on the subject. The typos and other errors Joshua mentioned
don't help, either.

Joshua:
> > 3. Several typos litter the place.


> Humm... not sure which you refer to. Some, as you mentioned, are just
> unconventional usages that may seem odd to native English speakers but
> more logical and easy reading to international readers.

Yeah, that was what was going through your mind - you did it for the
people. Uh-huh.

That makes no sense. Bad English is better if it is less intelligible
to fluent English speakers? Huh?

Sounds pretty iffy to me. The usual practice is to adhere better to
standards that foreign speakers probably learn, rather than to deviate
from them and claim speciously that such deviations enhance
readability when the effect is almost certainly the exact opposite.

Fix the flaws, don't make excuses for them.

Joshua:
> > 4. Sacrifices correctness for approachability. Specific examples:
> > 4a. "lines enclosed between '/*' and '*/' are ignored." Lexically, those
> > indicate the start and close of a comment token, so that it's not
> > "lines" that are ignored, but "characters" (which is even a bit
> > imprecise, since it's actually collecting output from the Unicode
> > preprocessing).
> > 4b. "special syntaxt [sic] to create jagged array in one shot." The
> > syntax isn't special, it's a standard array creation and assignment
> > expression.

Xah:
> it is rather ad hoc when one considers the generality or regularity of
> the syntax with respect to syntax design among computer languages.

You called the article your "Java tutorial". There is no "generality
or regularity of the syntax with respect to syntax design among
computer languages" because you claim to be speaking specifically
about Java.

How you can make such a claim yet justify deliberately providing
incorrect information in the name of some strange "generality" is a
mystery.

> Yes, practical and basic programing concepts are emphasized in this
> tutorial. I might change the spelling of “constructer” to
> “constructor” as you suggest. Note however, that “constructer” is more
> logical and a standand alternative, shown in most if not all English
> dictionaries. (you didn't find it OED?? i don't have access to Oxford
> Eng Dict atm but i doubt its not in it)

"Constructer" is incorrect spelling. It is not correct. It is
neither "logical" nor "standard". It is just plain wrong.

If you can't even correct a misspelling, instead making up some
garbage to excuse it, then your entire so-called "tutorial" cannot be
trusted. A person who cannot admit that they have made a mistake
cannot be trusted to correct their mistakes.

> > 5. Violation of several accepted conventions.
>
> You mean English writing conventions or some java programing
> conventions? Again, some of these are intentional. The alternative
> form i [sic] used usually is based on simplicy or logical consistancy.

So you admit do being wrong, but justify it on the basis of some
idiolectic principle of "simplicy [sic]" and "consistancy [sic]", two
words you couldn't even spell correctly.

Joshua:
> > 6. Pointing people to bad practices, such as shoving a static method
> > into a non-static context.

Xah:
> Again, basic, practical, to-to-point programing is emphasized. I

"Basic, practical, to-to-point programing" (what is "to-to-point
programing [sic]"?) is not a justification for doing bad things.
There is a reason why bad practices are labeled as such. Promulgating
bad practices is bad enough; trying to con people into thinking that
there is any "practical" benefit to doing so is inexcusable.

> discussed in the intro a bit, many things typical in Java tutorial
> such as tips on current Software Engineering issues, or discussing the
> lang from computer science point of view such as stacks, memory
> allocation, etc, are not used here. (personally i [sic] find them
> detrimental)

Which is why your tutorial is detrimental to anyone wanting to learn
to program well in Java. You admit to doing bad things in the
tutorial on purpose, in the name of vague and unjustified principles
that actually you violate. This is not desirable in a tutorial.

Joshua:
> > I'll stick with <http://java.sun.com/docs/books/tutorial/index.html>,
> > thank you very much.

Amen to that, brother!

--
Lew

Xah wrote:
....
> Yes, practical and basic programing concepts are emphasized in this
> tutorial. I might change the spelling of “constructer� to
> “constructor� as you suggest. Note however, that “constructer� is more
> logical and a standand alternative, shown in most if not all English
> dictionaries. (you didn't find it OED?? i don't have access to Oxford
> Eng Dict atm but i doubt its not in it)
....

I found "Constructer: See Constructor" in the OED Compact Edition, and a
similar entry in Webster's New Twentieth Century Dictionary. Both
dictionaries treat "constructor" as the primary spelling with
"constructer" as an alternative.

More significantly, I checked the index in each of a random selection of
C++, Java, and OO programming books. Each had an entry for at least one
variant on "constructor" but nothing for "constructer".

Based on that, I would say that "constructor" is preferred in
non-technical contexts, and is the right spelling for the OO programming
technical term. Of course, its use in the JLS makes it the correct
spelling in connection with Java programming.

Patricia

I have changed the spelling of constructer to constructor now.

Thanks all.

Xah
∑ http://xahlee.org/

☄

On Jun 30, 7:05Â*pm, Lew <l...@lewscanon.com> wrote:
> Patricia Shanahan wrote:
> >Xahwrote:
> > ...
> >> Yes, practical and basic programing concepts are emphasized in this
> >> tutorial. I might change the spelling of “constructer� to
> >> “constructor� as you suggest. Note however, that “constructer� is more
> >> logical and a standand alternative, shown in most if not all English
> >> dictionaries. (you didn't find it OED?? i don't have access to Oxford
> >> Eng Dict atm but i doubt its not in it)
> > ...
>
> > I found "Constructer: See Constructor" in the OED Compact Edition, and a
> > similar entry in Webster's New Twentieth Century Dictionary. Both
> > dictionaries treat "constructor" as the primary spelling with
> > "constructer" as an alternative.
>
> > More significantly, I checked the index in each of a random selection of
> > C++, Java, and OO programming books. Each had an entry for at least one
> > variant on "constructor" but nothing for "constructer".
>
> > Based on that, I would say that "constructor" is preferred in
> > non-technical contexts, and is the right spelling for the OO programming
> > technical term. Of course, its use in the JLS makes it the correct
> > spelling in connection with Java programming.
>
> Precisely so,Xah. Â*One should use the appropriate technical term for the
> topic under tutorial, in this case "constructor" for Java (and every other
> computer language that has them, Mr. General Programming Principles), or else
> one is teaching the innocent victims of your misinformation the wrong thing.
>
> It is a huge responsibility to teach, and in this forum I dare say a huge
> responsibility to teach Java. Â*You don't go around presenting yourself as a
> teacher of the language when you don't have the industry to research the
> topic, the diligence to report it correctly, the humility or honesty to admit
> error, or the commitment to do well for your students. Â*Such dismal
> irresponsibility is contemptible.
>
> --
> Lew