Contents

  1. Learning Objectives
  2. Introduction
  3. Syntax
  4. Errors
  5. Comments
  6. Formatting

Learning Objectives

  • Understand what Java is and does.
  • Understand what the term syntax means.
  • Be able to distinguish among a compiler, run-time, or logic error.
  • Understand what a comment is used for.
  • Be able to write useful and sufficient comments.

Introduction

Java is a compiled language, meaning that when we write our code, a tool, called a compiler will translate it from Java into something that a machine can understand. Java is also sufficiently high-level, meaning that Java programmers do not need to have an understanding of the machine the program runs on.

Java has an entry point called main. We can write a bunch of code, but Java sets aside this name, main, as the name it will first go to to run Java code. The entry point must be inside of a class. A class is just a named grouping of code (statements) and data (variables).

class test {
   public static void main(String[] args) {
      /* Java starts here */
      System.out.println("Hello Java!");
   }
}

If we look at the code above, we can see that we’re grouping the code in a class called test. In Java, we name our source code files the same name as the class and add the extension .java. For example, we would write the code above in test.java.

You can see there are a bunch of keywords before main, and then something in parentheses. The first keyword is public. We will learn more about access protection, but public means that main should be accessible outside of the class–by the Java machine itself. The keyword static means that main is agnostic of the class that it is in. We will discuss instances and memory later. Then a return type called void is listed. This just means that main does not return any data. Java doesn’t know what our program is going to do, so if we want to output data, WE as the programmer have to figure out how to do it. Luckily, Java makes this easy by giving us the System.out and System.in classes.

The String[] args is called a parameter. Java will automatically provide our main with a parameter, which is an array of Strings. A String is just a sequence of characters, like the text I’m writing here. An array of Strings can be thought of as several words under one name. We will use arguments later.

Syntax

You can see that in Java, we group code using curly braces { and }. Anything in-between the curly braces are grouped. For example, you can see that the code I wrote under main is inside of { and }, meaning that the code belongs to main. You can also see the ‘.’ (dot) operator. Java uses something called the object model. Each object can be thought of like a tree of other objects. In the System object, we have both in (input) and out (output). Then, from the in and out objects, we have functions like print and println (print line).

The screenshot above comes from the Java documentation. You can see that the class System contains err (error), in (input), and out (output). If we examined the out (output), we can see that it opens up to even more fields.

The screenshot above is just a few of the many methods inside of the out object.

You can see that the code that “does something” is ended with a semi-colon, ‘;’. The semicolon tells Java that we’re done with that one statement, and that we’re ready to move onto the next. The following code shows multiple statements. Take note that each statement is ended with a semicolon.

class test {
   public static void main(String[] args) {
      int a = 10;
      int b = 20;
      System.out.print(a + b);
   }
}

Java is case-sensitive, meaning that String and string mean two different things. If you are not careful, you might write something like: void Main, and Java will not be able to find it due to case-sensitivity.

Errors

As with everything, to err is human. Java will be no difference. There are three types of errors that we might encounter with java: (1) compiler, (2) run-time, and (3) logic.

A compiler error is caught by the Java compiler. Usually this is if we leave off a semicolon, do not have an ending parentheses, or are missing a curly brace. Essentially, a compiler error means that we did something that the Java compiler itself doesn’t understand.

A run-time error is caught by the Java machine (not compiler). A run-time error means that we met all the rules of the Java syntax, but something happened when the program was running that the machine did not like. This could mean that we tried to access memory we don’t have permission to read or write.

A logic error can only be caught by testing the code. A logic error is an error in the logic of your code. A logic error meets all of the rules of the Java compiler and the Java machine, but the result is incorrect. This usually means that we made a mistake in our logic, hence the term. The following code demonstrates a logic error.

class test {
   public static void main(String[] args) {
      double x1 = -2.0;
      double y1 = 1.0;
      double x2 = 1.0;
      double y2 = 5.0;

      double dist = Math.sqrt(Math.pow(x2 + x1, 2) + Math.pow(y2 + y1, 2));

      System.out.println(dist);
   }
}

The code above runs and prints a number. Unfortunately, the number is NOT the distance between (-2.0, 1.0) and (1.0, 5.0). The reason is because I added (+) x2 and x1 as well as y2 and y1 where the distance formula has us take the difference!

Java would have no idea what you are trying to do, so it just thinks you know best. It compiles and runs and gives output. Java is just doing what you told it.

Comments

Comments are statements we can add to Java that are removed prior to it being compiled. Comments are for humans who will read your code and not the Java compiler itself. Comments can be started with two forward slashes // or between a slash-asterisk and an asterisk-slash /* */.

The two forward slashes // comments the entire lines. The slash-asterisk will comment multiple lines until it reaches */

class test {
   public static void main(String[] args) {
      // This will comment this line
      /*
         All of these
         lines
         are
         comments.
      */
   }
}

Again, comments are not compiled by the Java compiler. Instead, they are used to relay to the reader the logic of your code. Comments should not be used to “instruct” the reader. Assume the reader knows Java. What the reader needs clarity on is your logic–the “why did you do this?”.

Writing comments is an art. Too many comments makes your code difficult to read, but too few comments makes your logic hard to understand.

What is a Good Comment?

The following code shows an example of how you should not comment.

// imports the Scanner class
import java.util.Scanner;
// Declare the class "test"
class test {
   // main function
   public static void main(String[] args) {
      // declare a
      int a;
      // declare b
      int b;
      // declare a scanner
      Scanner scan = new Scanner(System.in);
      // scan a
      a = scan.nextInt();
      // scan b
      b = scan.nextInt();
      // add a and b 
      int result = a + b;
      // print a + b
      System.out.println(result);
   }
}

There are a few things wrong with the code and comments above.

  • The comments describe what Java is doing, not the logic of the code. If I removed all of the Java code, I would have no idea what the program is supposed to do.
  • Every line is commented. Comments can get in the way of reading the code if I have to skip every line before I get to the next line of code. Instead of commenting every line, it is better to comment blocks of code. This will also help your comments be concise and document the logic of the code instead of Java.
  • The variable names are not very descriptive. Who knows what int a and int b are going to store? If I read it down by a few lines, I would have to remember what a was for and what b was for.
// test.java
// This program takes two integers from the user, adds them,
// and prints the result.
// Stephen Marz
// 31-March-2021

import java.util.Scanner;
class test {
   public static void main(String[] args) {
      Scanner scan = new Scanner(System.in);

      int left_operand;
      int right_operand;

      // We need the left and right operands before we can
      // add them. Use the scanner to extract out the next two
      // integers.
      // NOTE: We should error check with hasNextInt(). Expect
      // a run-time error if the user doesn't provide two integers.
      left_operand = scan.nextInt();
      right_operand = scan.nextInt();

      // At this point, we have both the left and right operands.
      // All we need to do is print their sum.
      System.out.println(left_operand + right_operand);
   }
}

Notice that the comments above now include a header, which describes the file and what it’s for. We will expect a comment header for all of your submissions. Second, notice that the comments are grouped. Instead of describing each line, we describe the logic. It’s understood that if we need input using nextInt(), that is the same thing that’s happening with the right_operand.

To determine if your comment is good, apply the following.

  • Does the comment describe the logic of the code or the code itself? (commenting logic not code)
  • Can you group more statements to a previous comment? (grouping blocks of code)
  • If I removed the Java code, could I understand what should go there? (is the comment detailed enough)

Formatting

The Java compiler does not enforce a particular format. Instead, it uses the braces {} and semicolons ‘;’ to tell it when a statement ends. For example, the code below is legitimate Java Code.

class
test 
{
public
static
void
main(String[] args)
{
System.
out.
println
("Hello Java");
}
}

The code above prints “Hello Java”. However, it is very difficult for us to read. This is why proper formatting is important. The code above is much easier to read when formatted, as it is below.

class test {
   public static void main(String[] args) {
      System.out.println("Hello Java");
   }
}

We generally indent for every curly brace { }. Notice that we see an open brace after class test, and then the next line is indented. The same thing happens after main’s open brace {. This technique will help you see your code in blocks. If I forgot a brace, it would be very obvious if the end brace } was missing, since at that indentation level, nothing would be there.

Spacing is also important. For many programs, they follow a general flow: (1) input, (2) process, (3) output. So, we can group all statements required to input data, group all the statements to process the data (arithmetic, conversion, etc), and group all the statements used to output the data.