2. Java

Java

We'll be programming in Java, a language many of you know, at least at a shallow level. Don't worry, we will go beyond the shallow level, but first, I want to make sure that everyone is up to speed, so we'll begin at the beginning. Here is the classic Hello World program in Java:

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

It hardly seems worth the effort to add comments to such a minimal program, but we will always add a minimum of commentary to all of our programs. The bare minimum is something like the following:

// HelloWorld.java
/**
 * Program to output the text Hello World to standard output
 * @author Douglas W. Jones
 * @version 8/27/2020
 */
public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, World.");
    }
}

Here, the first comment in the file is // HelloWorld.java This simply states the file name that this program is expected to occupy. Java (unlike many other programming languages) reqsuires that the file name for a source file match one of the classes defined in that source file, but that class definition may come much later in the file, after many comments, import directives, and even other class definitions. Therefore, in this class, we adopt the requirement that every source file begin with a comment giving the expected name of that source file.

The second comment is written in a special comment language called Javadoc. This is input to a program, also called Javadoc, that builds a web-site that documents Java programs. We will always write at least minimal Javadoc comments for every program we write, and as our programs grow, we will start exploring how Javadoc can help build useful roadmaps to the code we write.

Use a text editor to create this program and then run it!

Hello world is not a very interesting program. Here is a more interesting one. it prints successive members of the Fibonacci series to standard output:

// Fibonacci.java
/**
 * Program to print successive Fibonacci numbers to standard output
 * @author Douglas W. Jones
 * @version 8/27/2020
 */
public class Fibonacci {

    /**
     * Recursive function to compute a Fibonacci number
     * @param i the index of the desired Fibonacci number
     * @return the i'th Fibonacci number
     */
    private static int fib( int i ) {
        if (i < 2) return i;
        return f(i - 1) + f(i - 2);
    }

    /**
     * Main program
     * @param args the command-line arguments, ignored
     * Calls fib(i) for successive values of i
     */
    public static void main(String[] args) {
        int i = 0;
        while (true) { // compute successive Fibonacci numbers
            System.out.println( "f(" + i + ")=" + f(i) );
            i = i + 1;
        }
    }
}

The above program is somewhat overcommented. At this point, these comments do not contribute much to understanding this code, but as the program grows, commentary at about this level of complexity will become essential.

In your programming assignments in this course, your ability to write appropriate comments will be a significant part of the grade. Failure to include a clear indicaiton of authorship in the head comments of a source file will be severely penalized.

Style

In any large programming project, it is a good idea to adopt style guidelines. If every programmer writes code in their own style, the mixture of styles can quickly lead to unreadable code. Large companies usually have in-house style guidelines, and programmers are responsible for adhering to the house style.

Sun Microsystems, the original corporate home of the Java programming language, developed a very well thought-out style manual, currently hosted on the Oracle web site:
-- https://www.oracle.com/technetwork/java/codeconventions-150003.pdf

This manual is long but well organized. Some key features of the coding conventions are:

• Lines should be no longer than 80 characters.
• Break long lines after commas or before operators and indent.
• Break long lines after commas or before operators and indent.
• One declaration per line with explanatory comments on the same line.
• Declare variables at the start of a block, not scattered among other code.
• Initialize variables where they are declared unless good reason not to.
• Opening braces of blocks go as in the code given above.
• Only one statement per line.
• One indenting level is 4 spaces.
• Indent one extra level for each block.
• Use blocks for the bodies of conditionals and loops (unless trivial).
• Blank lines separate significant chunks of code.
• Never more than two consecutive blank lines.
• Space between keyword and parenthesis: if (this) {
• No space between method name and paren: method( that );
• Class names begin with capital letters;
• Variable names begin with lower-case letters;
• When a name is a phrase, capitalize first letters: namePhrase

Like just about every set of coding convetions, these are a bit long. Furthermore, they are just conventions. There come times when the conentions don't fit the problem. Intelligent and thoughtful violtion of coding conventions is not a problem, particularly if the overall appearance of the code gives the impression that the conventions are being followed.