Sunset in Quetico wilderness

Java Markup Approach

Just like we can identify parts of a sentence to get clues about what it means. We probably did this if we learned another language after our native one. For languages we speak fluently, we do this parsing of sentences automatically since our brains have so much practice putting sentences together and taking sentences we hear or read apart to uncover its meaning.

This approach to marking up java code facilitates learning the structure of the java language. It involves reading the code several times and classifying the code according to its function in the program. We also make connections between methods and objects using lines written on the page. This process is best completed on paper, since drawing lines over text documents on the computer is very tedious.

Practice exercises

After working through this tutorial which takes a short program through these phases, work through this more challenging exercise using a program's code that generates sample quality control data and evaluates X number of samples. The source is found on Git-Hub here--and you're encouraged to try running the code before marking it up.

Exercise Blank Worksheet in PDF

Exercise Blank Worksheet in Word format

Exercise KEY in Word format

Exercise KEY in PDF

The color-coding schema is summarized in this graphic:

Class/Object types

Method Declarations

Identifiers

Operators

Method calls

Note that these five categories are only one approach to dissecting Java code among many legitimate approaches. The goal of this color scheme is to draw attention to the method/method call structure that underlies all Java classes.




Phase overview

Phase 1: Read and classify the code

Phase 2: Check the classifications for accuracy

Phase 3: Mark the object and method connections

Phase 4: Learn about an unfamiliar components of the program

Phase 1: Read and classify the code

Review the sample code we'll use throughout this tutorial. The code defines a class called JavaParts and it prints out information about a possible future Linux-oriented world.

Java code markup - sample without highighting

Using the color classifications provided above, highlight your code. The following ordered list provides a useful order for doing so:

  1. Carefully read the code once or more times through to get a gist of what is happening. As you read, ask yourself where the class boundaries and methods are, etc.
  2. Now grab the highlighters: Mark the class declaration in yellow and create a right-facing bracket along the left margin of the paper that extends along the entire length of the class and closes at the closing curly brace of the class.
  3. Follow the same idea of number 1 for each method in the class. You should now see the overall structure of the class: a class block and its methods are all inside that class
  4. You've got the methods, now highlight the calls to each method in green. Draw a line from the call to the declaration.
  5. Grab the operators: the assignment operator = and the access operator dot . are the most important in the language! Start with them and think about what they are assigning or accessing.
  6. Highlight the other class names / object types yellow. Include "System.in" as an object type, even though the way those objects work is unusual.

Each color category is explained in its own section below. Throughout this tutorial, the Oracle java documentation is referenced. The entire table of contents for the tutorial is linked here.

Class Names and Object types

A Java class forms the basis of all Java programs. Each and every line of executed code exists inside a class with a name. Start by identifying the class that you're reading and any references to any other Java classes, perhaps those in the Java standard library, such as the System class.

Classes also form the basis of the notion of an Object's type. All objects have a type, which is identified by the name of the Java Class which produces that object. Our "System" object that we use to print to the screen is of type System. Highlight all Object type names and Class declarations yellow. Underlining represents the yellow highlighting.

Java code markup - classes only

Note that the class name JavaParts is declaring a class whereas String[] and System are declaring the type of object used or referenced. System.in is a reference to the System.in type object that is used to access the println() method, which sends text to the console (the screen). We would say that "we are calling the println method on the System object".

Method Declarations

We create methods in our classes to accomplish tasks, such as performing some math, or processing some request from the user, or to display a set of data. Methods are created by first declaring the method. Method declarations follow this basic structure--note that any text in [brackets] should be replaced with Java code:

[access modifier] [type:static or non-static] [return type] [method name] ( [parameters] )

Java code markup - methods and classes

Note that we use the blue highlighting to create a bracket around the entire method declaration block. In this case, we only have one method, called main, and it carries out all the tasks we want to accomplish in this program. Most classes will have a main method and several other methods.

Variable Names (identifiers)

Y. Daniel Liang defines identifiers as "the names that identify the elements such as classes, methods, and variables in a program." Broadly speaking, and identifier is the name for a variable. We use identifiers all over the place. Oracle's documentation on variables as identifiers details the various ways variables are used.

Java code markup - methods and classes and variables

When we declare a new identifier, we must give it a type. In the example above, we create three new identifiers of type int and named macUsers, pcUsers, and linuxUsers. We can declare all of these variables on the same line since they are all of type int. We use them throughout the rest of the method, so we like to declare them at the beginning of our method's code to make reading that method more straightforward.

Operators

Oracle's documentation defines operators as "special symbols that perform specific operations on one, two, or three operands, and then return a result." You can see a list of all the operators in Java on that tutorial page as well. Operators, like operations in math class, have a precedence of evaluation, and this order is unique to each programming language, so reviewing the order is important for any but the simplest of tasks.

Java code markup - methods and classes and variables and operators

We use three different operators in this program: the = operator, which is called the assignment operator, the dot . access operator, and the + concatenation operator. Let's look at each one individually and see that each operator behaves diferently. But each of them result in one or more values being combined into a single value. We call statements that result in a single value an "expression".

The all important, small-but-mighty dot (.) access operator:

The most important operator in Java is one that is also the smallest: the dot, typed with a period on the keyboard. I could not find Orale's official name for this operator on its tutorial page for objects, so we'll call it the access operator. The dot allows us to access methods and member variables on any object.

In the case of our sample program, we use the access operator to access the method println() on the System object (which has an out object we also access with a dot . operator.

The assignment = operator

The assignment operator = is at the core of the langauge because this allows us to give variables a value and change those values as we wish throughout the program. In our case, we first see the assignment operator to assign the int variable macUsers a value of 10. We then use that variable value in the next line, which we multiply by the MULTIPLIER constant, and store that value in the variable pcUsers. Note that the assignmetn operator evaluates the expression on its right and stores it in the varaible on its left. It requries variables on the left, and an expression on the right.

The Concatenation + operator

We see the concatenation + operator inside our method calls to println. This + operator is not adding together values as we do in traditional math but rather it is combining String literals "quoted text" with variable values, in our case, integers. The computer can only print text, so the println method actually converts our integers into numeric digits when it combines the macUsers, pcUsers, and linuxUsers with the "quoted text".

The multiplication * operator

This * multiplication operator works as expected. It tells the compiler to multiply the value on its left with the value on its right. We then stored the result of this operation in variables using the = assignment operator.

Method calls

A method call is the means by which we tell the Java virtual machine to continue execution of the program in the block of code that is declared as a method in the clas we specify. In other words, when we want the method to "do its thing" we have to call it up, and tell it to "go, do your thing". At this time, we must provide that method with an appropriate expression for each of its parameters.

In this code, our only method call is to the System objects println() method. Note that we underlined the values inside the ( ) because whatever is inside the ( ) gets sent to the method we are calling. These values are called arguments to the method. The arguments are part of the method call, but we highlight them separately in this approach so we can see the parts of Java that we are sending as arguments.

Java code markup - methods and classes and variables and operators and method calls

One final note is that our main() method is never explicitly called by us programmers. The Java Virtual Machine (JVM) calls the main() method by itself as its way of starting the program running. When the program reaches the end of the main() method, program execution terminates.

Elements we did not color code but you could still mark up

Phase 2: Check the classifications for accuracy

If you are marking up code for class, there's a good chance Eric posted a key on the website somewhere. Check your work against this key. If you made a mistake, please identify that mistake in writing. Perhaps you marked an identifier as a class name. Write "identifier, not class". This will help your brain work toward greater accuracy.

Without a key, use the definitions above and the linked examples to check your work. Have a mentor or peer or tutor review your work and discuss discrepancies with you.

Below is another image of the completed markup of the JavaParts class that is similar to the class we created in our first two sessions of Java.

Java code markup - methods and classes and variables and operators and method calls

Notes on this example

Phase 3: Mark the object and method connections

The most interesting part of a class markup is connecting each of the object references to a little object diagram we'll make in the margins.

Follow these steps:
  1. Build class diagrams in rectangles in the margins for each class referenced in the code. Each time an object is created or referenced, draw the class box with the class name in the top box, member variables in the second box, and methods in the lower box. You don't need to look any information up to do this, since you have the class names in the code (makes sense, otherwise the compiler would not know which Objects methods are being called on!)
  2. Draw lines from the method calls to the method signatures in the mini-class diagrams in the margins.
  3. Sit back, rest your hands behind your head, and marvel at all that good JavaThinking you just did!
Java code markup - methods and classes and variables and operators and method calls

Phase 4: Learn about an unfamiliar components of the program

You may very well encounter classes you know nothing about except for the method or member variable you see in the code. If you wrote the code yourself, you should already have read the documentation about every class you use. But if you are marking up code you didn't write, browse the Java API documentation which will likely contain a thorough write-up of any class you'll encounter in this introductory course.

The most notable new class in this example is the System class which contains member variables and methods that relate to the way the Java program can interact with the computer machine on which it is running. We can read all about the system object on the Java 8 Application Programming Interface documentation (The Java API).

`