Tools: the Command Line, Checkstyle, and JUnit

1. Tools: the Command Line, Checkstyle, and JUnit

Title

Think Java 2e · Chapter A · Tools

Sections A.1-A.8 · pp. 297-307

2. What you will be able to do

Objectives

This lesson follows Think Java 2e, Chapter A (Tools), Sections A.1-A.8, pp. 297-307. Everything on these slides can be checked against those pages.

1. Distinguish the JDK, the JVM, an IDE and a text editor.

2. Compile and run a Java program from the command line, and say what each command needs.

3. Automate a test using redirection operators and diff.

4. Explain what a style checker can and cannot evaluate.

5. Use a debugger's breakpoints and call stack to trace execution.

6. Write a JUnit test class and explain the argument order of assertEquals.

• A.1 — Installing DrJava
• A.2 — DrJava Interactions
• A.3 — Command-Line Interface
• A.4 — Command-Line Testing
• A.5 — Running Checkstyle
• A.6 — Tracing with a Debugger
• A.7 — Testing with JUnit
• A.8 — Vocabulary

3. Retrieve before you read

Warm-up

Three things from the very first chapters, now seen from underneath.

4. What you actually need to run Java

Concept

If you want to compile and run Java programs on your own computer, you will need the following — and it is worth knowing which piece does what.

• A.1–A.2 — the JDK, an IDE, and the Interactions pane
• A.3 — the command-line interface
• A.4 — automating tests with redirection and diff
• A.5–A.6 — Checkstyle, and tracing with a debugger
• A.7 — testing with JUnit

Downey & Mayfield, Think Java, 2nd edition (Green Tea Press / O'Reilly, 2020) — Think Java 2e, Chapter A (Tools), Sections A.1-A.8, pp. 297-307 — Appendix A begins on printed page 297.

5. The pieces of a Java setup

Section

Sections A.1-A.2

6. Four things, and only one of them is required

Concept

The easiest way to start programming in Java is to use a website that compiles and runs Java code in the browser. If you are unable to install software — which is often the case in public schools and Internet cafés — an online environment covers almost everything in this book.

JDK — The Java Development Kit, which contains the compiler, Javadoc, and other tools.

JVM — The Java Virtual Machine, which interprets the compiled byte code.

IDE — An integrated development environment that includes tools for editing, compiling, and debugging programs.

text editor — A program that edits plain text files, the format used by most programming languages.

A text editor such as Atom, Notepad++, or Sublime Text, and/or an IDE such as DrJava, Eclipse, jGrasp, or NetBeans. The book recommends OpenJDK, an open source implementation of Java SE, and DrJava as a beginner's IDE — but every idea in this appendix applies to whichever tools you end up using.

7. What a JAR file is

Notation

Two of this appendix's tools ship as JAR files, and the vocabulary entry explains why that is convenient.

A single file that contains an entire program and its resources is the reason JARs exist. It is the same idea as any archive format, applied to the unit Java actually ships in.

8. The Interactions pane

Worked example

One of the most useful features of DrJava is the Interactions pane at the bottom of the window. It provides the ability to try out code quickly, without having to write a class definition and save/compile/run the program.

> int x = 5;
> int y = 3;
> x > y
true
> x % y
2

9. What does the JVM do?

Prediction

Two tools, two jobs.

javac Hello.java     // produces Hello.class
java Hello           // ?

10. Why the book kept this out of the main text

Concept

We avoided putting these details in the main text, because they can be distracting. The decision is worth noticing.

The tools in this appendix have already shifted since it was written — DrJava is no longer widely used, and JUnit has moved on two major versions. The ideas have not: automated tests, style checks, breakpoints and a call stack are as relevant as ever, which is exactly why they were worth separating from the syntax.

11. Confusing the JDK with the JVM

Trap

$ javac Hello.java
javac: command not found

# but this works:
$ java -version
java version "17.0.1"

# The Java Development Kit includes:
#   javac    the compiler
#   java     the JVM
#   javadoc  the documentation tool
#   jar      the archive tool

12. Which tool for which job?

Definition probe

Four pieces of a setup.

13. Why no semicolon?

Prediction

In the Interactions pane.

> int x = 5;
> x > 3

14. Why is an interactive pane so useful?

Explain it to yourself

You could always write a small main method.

15. The command line

Section

Section A.3

16. Four commands to start with

Concept

One of the most powerful and useful skills you can learn is how to use the command-line interface, also called the terminal. The command line is a direct interface to the operating system.

$ cd Desktop
$ ls
Hello.java
$ javac Hello.java
$ ls
Hello.class    Hello.java
$ java Hello
Hello, World!

command-line interface — A means of interacting with the computer by issuing commands in the form of successive lines of text.

On Unix systems like Linux and macOS, you can get started with just four commands. It allows you to run programs, manage files and directories, and monitor system resources. Many advanced tools, both for software development and general-purpose computing, are available only at the command line.

17. A file name against a class name

Notation

The two Java commands look symmetrical and take different kinds of argument. That asymmetry catches everyone once.

Knowing what your IDE is doing for you is worth the ten minutes it takes to do it by hand once. When the IDE goes wrong, the command line is where you find out why.

18. Compiling and running by hand

Worked example

Figure A.3 shows an example in which the Hello.java source file is stored in the Desktop directory.

$ cd Desktop
$ ls
Hello.java
$ javac Hello.java
$ ls
Hello.class    Hello.java
$ java Hello
Hello, World!

19. What file does javac produce?

Prediction

Compiling Hello.java.

$ javac Hello.java
$ ls

20. Why it is worth learning

Concept

The appendix makes an unusually strong claim for a textbook, and it is worth taking seriously.

Taking time to learn this efficient and elegant way of interacting with the operating system will make you more productive. People who don't use the command line don't know what they're missing. The next section is a concrete example: automated testing, which needs the command line and takes four steps.

21. Passing the wrong thing to java

Trap

$ java Hello.class
Error: Could not find or load main class Hello.class

$ java Hello.java
# on older JDKs: an error
# on newer ones: compiles and runs in one step - a different feature

$ javac Hello.java      # file
$ java Hello            # class

22. Which command?

Definition probe

Four commands, four jobs.

23. Compile and run

Fill the middle

One takes a file; one takes a class.

24. Why do professionals still use the terminal?

Real world

Every IDE has buttons for all of this.

25. Command-line testing

Section

Section A.4

26. Stop retyping the same input

Concept

Most, if not all, testing is based on a simple idea: does the program do what we expect it to do? For simple programs, it's not difficult to run them several times and see what happens. But at some point, you will get tired of typing the same test cases over and over.

java Convert < test.in > test.out

redirection operator — A command-line feature that substitutes System.in and/or System.out with a plain text file.

The basic idea is to store the test cases in plain text files and trick Java into thinking they are coming from the keyboard. The program is not modified at all — it still reads with a Scanner and prints with println, and neither notices.

27. The two operators

Notation

One line does two different things, and the direction of each arrow is the whole of it.

Redirection is an operating-system feature, not a Java one. Any program that reads standard input and writes standard output can be tested this way, in any language.

28. A complete test in four steps

Worked example

Here are step-by-step instructions for testing the Convert example from Chapter 3.

# 1. test.in  - the input
193.04

# 2. test.exp - the expected output
193.04 cm = 6 ft, 4 in

# 3. run it
java Convert < test.in > test.out

# 4. compare
diff test.exp test.out

29. What does `<` do?

Prediction

Two operators, two directions.

java Convert < test.in > test.out

30. When the test fails

Concept

If the files are the same, then the program outputted what we expected it to output. If not, then we found a bug, and we can use the output to begin debugging our program.

Usually, the program is at fault, and diff provides some insight about what is broken. But there's also a chance that we have a correct program and the expected output is wrong. That last possibility is worth remembering: a failing test is evidence that two things disagree, not proof of which one is wrong.

31. Comparing by eye instead of with diff

Trap

expected:  193.04 cm = 6 ft, 4 in
actual:    193.04 cm = 6 ft, 4 in␣

# looks identical. It is not.

diff test.exp test.out

32. What does diff print on success?

Prediction

The two files are identical.

diff test.exp test.out

33. Which file is which?

Definition probe

Three files, three roles.

34. Why store test cases in files?

Explain it to yourself

You could just type them each time.

35. Checkstyle and the debugger

Section

Sections A.5-A.6

36. A tool that reads your style

Concept

Checkstyle is a command-line tool that can be used to determine if your source code follows a set of style rules. It also checks for common programming mistakes, such as class and method design problems.

java -jar checkstyle-*-all.jar -c /google_checks.xml *.java

Hello.java:93:5: Missing a Javadoc comment

wildcard — A command-line feature that allows you to specify a pattern of filenames by using the * character.

**The * characters are wildcards that match whatever version of Checkstyle you have and whatever Java source files are present. The output indicates the file and line number of each problem. /google_checks.xml is inside the JAR file and represents most of Google's style rules.**

37. What a style checker cannot do

Notation

The appendix is careful to bound the claim, and the boundary is the interesting part.

A style checker enforces the part of quality that can be mechanised, which is real and small. The rest is judgement — and knowing which is which stops you mistaking a clean report for good code.

38. Tracing with a debugger

Worked example

A great way to visualize the flow of execution, including how parameters and arguments work, is to use a debugger.

// Most debuggers make it possible to do the following:
//
//   Set a BREAKPOINT, a line where you want the program
//     to pause.
//   STEP THROUGH the code one line at a time and watch
//     what it does.
//   Check the VALUES OF VARIABLES and see when and how
//     they change.

39. What is a breakpoint?

Prediction

You set one before running.

// Ctrl+B toggles a breakpoint on the current line

40. Print statements against a debugger

Concept

Lesson 15b traced a binary search with System.out.println. A debugger does the same job differently.

Neither replaces the other. A print statement survives into a log and works in places a debugger cannot reach; a debugger shows you everything without deciding in advance what to look at. Knowing both means picking the one that fits — which the appendix says explicitly about the command line too.

41. Editing code while it is paused

Trap

// paused at a breakpoint, you add three lines above it
// and delete one below

// the debugger's line numbers no longer match the file

// 1. run to the breakpoint
// 2. inspect variables, step, work out what is wrong
// 3. STOP the program
// 4. then edit and recompile

42. Can a style checker judge it?

Definition probe

Mechanical rules against judgement.

43. Match the tool to its job

Matching

Four tools from this appendix.

44. What does the call stack tell you?

Socratic

You might be surprised to see how many methods were called before the main method!

45. Testing with JUnit

Section

Section A.7

46. How beginners test, and why it does not scale

Concept

When beginners start writing methods, they usually test them by invoking them from main and checking the results by hand.

public static void main(String[] args) {
    if (fibonacci(1) != 1) {
        System.err.println("fibonacci(1) is incorrect");
    }
    if (fibonacci(2) != 1) {
        System.err.println("fibonacci(2) is incorrect");
    }
    if (fibonacci(3) != 2) {
        System.err.println("fibonacci(3) is incorrect");
    }
}

This test code is self-explanatory, but it's longer than it needs to be, and it doesn't scale very well. In addition, the error messages provide limited information. Note it does use System.err rather than System.out — the error stream, which is at least the right channel.

47. The naming convention

Notation

JUnit relies on names matching, and the rule is worth learning because tools everywhere use it.

The naming is not cosmetic. A test suite of two hundred methods is navigable only because each name says exactly what it covers — which is the same argument as good variable names, at a larger scale.

48. A JUnit test class

Worked example

JUnit is a common testing tool for Java programs. To use it, you have to create a test class that contains test methods.

import junit.framework.TestCase;

public class SeriesTest extends TestCase {

    public void testFibonacci() {
        assertEquals(1, Series.fibonacci(1));
        assertEquals(1, Series.fibonacci(2));
        assertEquals(2, Series.fibonacci(3));
    }
}

49. Which argument comes first?

Prediction

assertEquals takes two.

assertEquals(1, Series.fibonacci(1));

50. Expected first, actual second

Concept

The first argument is the expected value, which we consider correct, and the second argument is the actual value we want to check. If they are not equal, the test fails.

assertEquals(1, Series.fibonacci(1));
//           ^  ^
//           |  the ACTUAL value - what your code produced
//           the EXPECTED value - what you say is correct

// JUnit provides additional assert methods:
assertNull(x);
assertSame(a, b);
assertTrue(condition);

Getting the order backwards does not break the test — it still passes or fails correctly. It breaks the message: a failure will report expected 5 but was 3 with the two the wrong way round, which is confusing exactly when you are least able to spare the confusion.

51. Testing only the cases you know work

Trap

public void testFibonacci() {
    assertEquals(1, Series.fibonacci(1));
    assertEquals(1, Series.fibonacci(2));
    assertEquals(2, Series.fibonacci(3));
}

public void testFibonacci() {
    assertEquals(1, Series.fibonacci(1));   // base case
    assertEquals(1, Series.fibonacci(2));   // base case
    assertEquals(2, Series.fibonacci(3));   // first recursive case
    assertEquals(55, Series.fibonacci(10)); // deeper
    // and decide: what should fibonacci(0) or fibonacci(-1) do?
}

52. What should the test class be called?

Prediction

The method under test lives in Series.

public class Series {
    public static int fibonacci(int n) { ... }
}

53. Write a JUnit test

Fill the middle

Expected first, actual second.

54. Why write tests at all?

Real world

You can always run the program and look.

55. Three ways to find out what your code does

Comparison

Fill the blanks.

The last row is why tests are worth the extra effort. A print statement helps you today; a test keeps helping — which is what makes refactoring safe six months later.

56. The pattern to carry away

Pattern

Make the check automatic, so it happens whether or not you remember.

# a test that runs without you typing anything
java Convert < test.in > test.out
diff test.exp test.out

# a test that names its own failure
public void testFibonacci() {
    assertEquals(1, Series.fibonacci(1));
    assertEquals(2, Series.fibonacci(3));
}

# a check you cannot forget to run
java -jar checkstyle-*-all.jar -c /google_checks.xml *.java

• The JDK contains the compiler; the JVM runs the byte code.
• javac takes file names; java takes one class name.
• < feeds a file into System.in; > captures System.out.
• A style checker cannot judge comments, names or algorithms.
• assertEquals takes the expected value first.

57. Check: the two commands

Check

Work it out before you click.

$ javac Hello.java
$ java Hello

58. Check: redirection

Check

Work it out before you click.

java Convert < test.in > test.out

59. Check: assertEquals

Check

Work it out before you click.

assertEquals(1, Series.fibonacci(1));

60. Tools change; the ideas do not

Real world

DrJava is barely used now and JUnit has moved on two major versions since this appendix was written.

61. How sure are you?

Commit first

Commit to an answer and to your confidence.

62. Explain it to someone else

Explain it

Two minutes, out loud.

63. Exit ticket

Exit ticket

One question before you close the deck.

64. Draw the whole lesson

Connect it up

One page, from memory.

65. Recap

Recap

Eight sections of machinery, deliberately kept out of the main text so it would not distract from the language.

• The JDK contains the compiler and tools; the JVM interprets byte code.
• An IDE is convenient and not required — a text editor and the JDK are enough.
• Four commands to start: cd, ls, javac and java.
• javac takes file names; java takes one class name.
• < redirects a file into System.in; > captures System.out into a file.
• diff prints nothing when two files match — silence is the pass condition.
• Checkstyle checks mechanical style and cannot judge comments, names or algorithms.
• A debugger gives you breakpoints, stepping, variable inspection and the call stack.
• JUnit's assertEquals takes the expected value first.