Get Programming with Java: Some concerns about the code examples

Let me start by saying that I really wish you the best with your book. I think it's great that you're focusing on objects early because that's the one thing a number of us regulars around here feel is sorely lacking in how students are being taught OO languages like Java. One of my pet peeves is seeing students who are writing very procedural-minded programs in an OO language and totally missing the point of OOP.

With that said, I do have some concerns with the code examples that I downloaded from the book's page on Manning.com.

I understand that this is still a work in progress so I can overlook the poor formatting of the code for now. Hopefully, that will get fixed before the book is released in its final form. (If you're looking for technical reviewers to help you with that, I'm available... not so subtle hint, hint )

However, it looks like you're already halfway through your manuscript and the code examples in the early chapters look like they still need a lot of work. Granted, I don't have access to the pertinent discussion in the book that would give more context but the code in listing2_3_PetClass.java looks like it's a copy-paste job that got forgotten: all three sections are the same. At first, I thought maybe this particular example was trying to demonstrate how different instances of a class are not equals() by default until you override that method. But then listing3_2_PetClass.java, which looks like it's the next iteration of that code only had changes to the fields' access modifier from package-private to private.

This makes me very curious about the progression of object-oriented concepts you're taking the reader through with these examples and what your focus is. In my opinion, OOP is mainly about object behaviors as codified by its accessible methods. To me, encapsulated data/fields are things that I prefer to frame as supporting features that enable an object's behaviors and not really the primary or distinctive aspect of an object. My concern is that the examples seem to suggest an emphasis on fields instead and the mechanics of accessing them. This tends to develop an implementation-focused mindset in programmers, something that I find myself having to teach professional developers to get away from all the time. I really would like programmers to be taught how to think in terms of intent and behavior first. (I am an Agile Technical Coach by day)

I guess my question then is this: What is your approach to teaching OOP in general and why, based on the code examples you have now, does it seem like you're focusing on encapsulated data/fields instead of behaviors first?

Corollary question: Would you consider experimenting with an approach of discussing from a behavior-centric perspective first (outside-in)?

I also want to add that as a professional software developer and coach, one of my passions that I try to pursue outside of my regular consulting work is developing collaborative relationships between academia and industry. I have done a couple of things in the past couple of years to move the needle on this. In 2017, through an interaction that started in these forums, I was invited to conduct a workshop on aligning academia and industry around newer development practices at a university in South Carolina. I have also collaborated with some professors at the University of Stuttgart (Germany) by doing code reviews for projects developed by upperclass CS students. Most recently, I have started a discussion with a colleague based in Atlanta, GA to see what we can do to develop the same kind of collaboration between our company and students attending the Georgia Institute of Technology.

Your bio says that you teach at PSU. Would you be interested in discussing academia-industry collaboration opportunities we could explore and perhaps develop? I think this can be very mutually beneficial.

Here's another example of code that has a number of issues. I am pasting this in exactly as it was downloaded from Manning.com by the way:

In file listing11_4_VehicleClass.java

Issue #1: Formatting / proper indentation - not a biggie if this gets fixed before the book goes live. I would add whitespace between methods and fix the indentation.

Issue #2: The compareTo() method.

1. It's missing the @Override annotation. I don't think including that would detract from students' ability to learn/absorb the material. It's important to include that annotation and I think it's important to encourage its use in the code. A small sidebar would be enough to highlight this point.

2. The implementation given does not adhere to the contract for compareTo(). Specifically, it does not have a case where it returns a negative number. That is an incomplete implementation and the reader should be made aware of that. In Chapter 11, there is a mention of the contract for compareTo but the example fails to adhere to it. No mention is made in the text that leads me to think the omission was intentional.

The JavaDocs wrote:Compares this object with the specified object for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

Junilu,
Thanks so much for your comments! Since this is still in the MEAP edition, it provides me with valuable feedback for changes I can include in the final version.

To answer your first question, I would be more than happy to talk about collaborating on work related to the combination of Academia and Industry. In my full-time role as a content manager for Linkedin Learning with Lynda.com content, it would also be great to think about potential gaps in our course offerings there too. I am the content manager for core programming languages and Java is a big part of the library.

In regard to the code formatting, it is a difficult compromise to provide enough white space and proper indentation and still keep the code so that it fits on one page for the printed copy. I struggle with this each time, but I will take your recommendation into account for the final version.

Finally, I agree with the annotation for the @Override, I will make sure that gets added. And regarding the return for the negative value in the compareTo, I think I left it out to conserve space, but I like your point about providing all necessary information to fulfill the contract of implementing Comparable, so I will also make that change.

I also really appreciate the offer to help provide technical review, but I'm working with Manning and we have a technical reviewer.

I also see an issue with the dissonance between the semantics of compareTo() as used in the example and the messages displayed by the code:

The compareTo() method is used to determine some kind of logical ordering of objects, not just equivalence. The messages that say the vehicles are the same or not the same could lead the reader to think otherwise.

The messages used in this example would be more appropriate to demonstrate the use the equals() method, in my opinion.

Using a Vehicle object to demonstrate the Comparable interface is a poor choice. This interface is meant to impose a natural ordering of objects. In my mind, there is no "natural ordering" for a Vehicle. What is a natural and intuitive ordering for vehicles? Alphabetically by make and/or model? By year? By size? There can be many orderings for Vehicles, depending on your requirements but I don't see one that is more "natural" than all the others.

It would make more sense to demonstrate implementations of Comparator as they would pertain to Vehicles, in my opinion. This way, you could show that you can use different Comparator implementations to sort by make or model or by year or by type/usage or by whatever other criteria, like engine size or reliability.

The issue regarding the example that uses Comparable instead of Comparator points to a bigger issue that underpins a common problem I see in how students are taught. There is a lot of focus on mechanics and syntax. That's fine, it's important to master those, otherwise, nothing you write will even compile. However, I do think that where many students fall way short when they are learning to write programs is in their ability to put context around the code they write.

It's like they're being taught how to drive a car in outer space. When you turn the steering wheel to the left or right, they are told that the wheels will also turn that way but they won't really see how that affects the motion of the car. You know what I mean? There's nothing there that will help them make the connections between their choices and their effects on the outcome.

I strongly believe in the proposition that coding/programming is a design activity. See Jack Reeves' essays on Code As Design. If we're to teach people how to program, we have to teach them about design at the same time.

What I mean about design, at least in the very early stages, includes this:

1. Program structure: must be clearly discernible how different parts of the solution are organized and how they relate to the functionality being developed.

2. Code clarity: must choose names that express intent clearly. You should be able to understand what the code is doing when you read it. You shouldn't have to spend more than a few seconds between reading the code and understanding what it does.

I think it is important to keep emphasizing these basic points when we're teaching people how to program, otherwise, they will get lost in the weeds of syntax and language mechanics and lose sight of the point of writing programs: to solve a problem and give its user some value.

I have never met anyone, novice or professional, who can read that code for the first time and understand what it does in less than 30 seconds.

By contrast, this code is very readable:

The moment you finish reading that method, you have a pretty good idea of what it does. Teaching problem solving techniques like decomposition and composition, focusing on intent, etc. seems to be regarded as being out of scope for many beginner type books. Even intermediate books seem to gloss over this. I don't know where the balance between these concepts and basic syntax and mechanics needs to be struck but I sure would like to experiment with getting more of it in beginner level teaching materials.

I have worked with students and used the above example to show them how professional development is done. I have gotten mostly enthusiastic responses from the students I have worked with on this example so I'm thinking it's not entirely beyond the realm of their abilities to comprehend.

Peggy Fisher wrote:In regard to the code formatting, it is a difficult compromise to provide enough white space and proper indentation and still keep the code so that it fits on one page for the printed copy. I struggle with this each time, but I will take your recommendation into account for the final version.

I can understand the constraints you'd have to consider for the printed version and I can even understand having to keep the same formatting even for the electronic version of the book. However, for the downloadable code, I think it would benefit whoever buys or uses the book to have the code properly formatted, with sufficient whitespace to improve readability. There is no space constraint for the downloadable code.

It is also very inconvenient at best and at worst, problematic for beginners to have the code in files that are not named properly so they can be immediately compiled. The README included with the download instructs the user to copy-paste the code into a file that has the same name as the class. That's just another barrier to using the code examples you provide and it's one that I'd predict a few users might have problems with.

I would experiment with having the chapters or sections as directories/packages and then putting the example code in properly-named and ready-to-use compilation units (.java files). You might even devote an appendix or a few sections of the README file to giving instructions on how to use the code examples in other popular IDEs like Eclipse or IntelliJ. Chapter 1 is already about how to use NetBeans anyway, so why not structure the downloadable ZIP file such that when you unzip it, you can readily import it as a project into NetBeans and run the code examples without going through the whole rigamarole of copy-pasting the code into correctly-named files?

The code in listing12_4_Student.java has the same semantic issues around implementing Comparable. I don't think that it's intuitive to say that the natural ordering for Student objects is based on GPA. Again, a Student class would probably be best associated with implementations of Comparator rather than being designed to implement Comparable.

Here's a snippet from that example:

This implementation does not include the @Override annotation and it does not adhere to the contract for compareTo() because there is no case where it returns 0. In fact, the given implementation is wrong because in the case where it should return 0, it will return -1.

Additionally, the example contains this construct:

Using == with boolean values is strongly discouraged and considered poor form.

First, it is easy to use "=" instead of "==" which often leads to a bug that can be difficult to find. We often see questions about this kind of bug here.

Secondly, comparing a boolean variable with true or false is unnecessary and redundant. This is how we recommend coding that instead:

An even better way to code this is to change the variable name so that you can avoid using the negation (!) operator which can be difficult to discern. This is more readable:

even better, in my opinion, is to reduce the cognitive weight by removing the idea of "not" altogether by finding a different name:

Are those files really called listing_xxx_Something.java? That worries me, because public top-level classes need to be in files with the same name. I would prefer to have different folders zipped into the downnload, but you are then going to have problems if there are package declarations complicating the compiling process.

Yes, that is the convention used. The README that currently comes with the download explicitly mentions the need to copy the code into an appropriately named file. I included a similar suggestion a couple of replies back for how to structure and name the files so there will be no need for the extra step of copy-pasting text.