Teach Java in 5-10 pages ?

[Bert Bates]

Hi Guys,

Imagine you want to teach some early intermediate programmers - in as few pages as possible - some basic, useful Java. Maybe a person who already knows some Python or some Swift, or Go, or C#.

My thought is that you could show a page of code that demonstrates the use of a lot of key language and API features. You would annotate the code, and maybe on subsequent pages zoom in on certain lines of code and explain them more carefully. But the idea is that all you get is 5-10 pages total. You might also include a diagram or two.

Here's a rough spec for a small program that might cover a lot of bases:

- Write a program that takes command line arguments.
- If the first argument is "sort" or "-sort", you will sort the subsequent arguments by natural (alphabetic) ordering.
- You'll write the (if appropriate, "sorted") arguments to a text file, and display the average length of the arguments.
- You should make an instance of the class, and show as many reasonable, commonly used language features as you can. Don't go overboard!
- FWIW, I used an ArrayList.

I've attached two pages from one of our Java certification books. This code doesn't do as much as I'm proposing, but it might give you an idea of how the 5-10 pages might end up looking.

What I'm mostly curious about is what such code might look like, and if you think a different spec might be better?

[Tim Holloway]

You didn't include any JavaDoc comments, Bert. Shame!

Yeah, I know it's not officially required as part of a complete program. But if you want to show people how to program like crap, teach them PHP or JavaScript.

[Bert Bates]

Hey Tim,

I'm guessing you're kidding, but you bring up a good point.

There are good moments in a book to show examples of how to properly comment your code. But for most of a good book, side annotations are a better teaching approach than things like JavaDocs.

[Tim Holloway]

Teaching approach?  

I JavaDoc EVERYTHING.

It's not about the importance of good commenting as such. It's about the fact that JavaDocs are in their own way just as much a part of the Java language as the executable statements themselves are.

JavaDocs, as everyone knows (I hope!) compile into a structured documentation package for the code. You can, in fact, make an entire logic manual complete with illustrations and long detailed statement-of-purpose descriptions using JavaDoc. Even Sun rarely actually did this, but it's there.

But even if you never RTFM, most IDEs can popup a hover when you code a method call, and that popup can show you things like what the method is actually good for and what those mysterious i, j, k parameters really mean and what their allowable values are.

JavaDoc, in short, is the sort of thing that separates programmers from amateurgrammers. If you want people to consider java as just another Visual Basic that's harder to code in than Python, skip the JavaDocs. But if you want them to see the difference between slapdash and industrial-grade products, that's one of the key differences. Even Python has a doc facility these days. Just not as many people use it.

[Bert Bates]

Tim,

You're preaching to the choir

But for THIS exercise, JavaDocs would add cognitive load.

[Tim Holloway]

Bert Bates wrote:Tim,

You're preaching to the choir

But for THIS exercise, JavaDocs would add cognitive load.

And maybe that's not such a bad idea. It's the "All You Have To Do Is..." mentality that has made such a mess of software.

In the movies, surgeons are all tense and sweating and working for a long time. Hackers just lean forward, mutter, type a few lines on a screen in a dark room with letters projected on the walls behind them (and the lenses of their glasses), and "boom" they just pwned the Pentagon. And now the CEO wants you to clone Amazon.com by Thursday because his 10-year-old kid can make a square bounce around a computer screen.

I'm not saying make things hard for the sake of making things hard or cultivating a mystique. I'm saying don't oversimplify by making shortcuts the norm. Or rather perpetuate the myth. Good software development is work. People should think about what they're doing. And in Literate Programming, you write the comments first anyway.