Short Guide on Writing Java

This guide goes through some of the mechanical elements of writing Java. This is focused on the syntax and structure of Java code, not on the semantics (behavior) of the code. This guide is intended to be applicable throughout the duration of the course, so it is not expected that you'll be able to understand every single bit of it all at once. For example, while the meaning of a comma (,) in Java code is discussed, we won't be seeing commas until later in the course.

Writing the Code Itself

Java code must be written in plain text, which is true of most programming languages. Text editors (e.g., jGrasp, emacs, vi, vim, Sublime Text, Atom, ...) will give you plain text straight out of the box. Word processors (e.g., Microsoft Word, Google Docs) generally don't give you plain text out of the box, and if you use these you'll need to explicitly have them save as plain text. Text editors are meant for writing things that can be read by both humans and computers, including code. This is why text editors are based around plain text: the text itself should be as simple as possible in structure to facilitate easy reading for both parties. Word processors are meant for writing things for humans. This is why word processors generally don't use plain text: they want to add in extra formatting which makes things easier for humans to read, but more difficult for a computer to understand. For example, word processors will try to make explicit left and right double quotes (i.e., “ ”), whereas text editors will use the same double quote character either way (i.e., ").

Beyond plain vs. formatted text, text editors generally better understand the syntax of programming languages. This means that text editors can do things like highlight your code and even automatically structure it. These features make code easier to read and write on a text editor. Word processors, in contrast, lack these features. In fact, a particularly aggressive word processor may try to “autocorrect” something which is syntactically valid (but strange-looking) into something invalid (but better-looking). With this in mind, word processors are altogether the wrong tools with which to edit code.

Components of Executable Java Code: Expressions and Statements

The part of your code which actually runs is divided into expressions and statements. In being executable, both expressions and statements do something. However, expressions and statements differ in exactly what they produce.

Expressions do something, and then produce some sort of value as a result. This is no different from the sort of mathematical expressions you're used to, such as 2 + 3. Mathematically, the expression 2 + 3 states to add 2 and 3 together, and the produced result of the expression is 5. Java expressions work in the exact same way, and the nomenclature of “expression” comes from the same source. In fact, 2 + 3, in addition to being a valid mathematical expression which produces 5, is also a valid Java expression which produces 5.

Statements, like expressions, instruct the computer to do something. However, unlike expressions, statements do not produce values as results, at least not directly. For example, consider the following Java statement:

System.out.println("Hello, world!");

The statement above is valid Java code which tells the computer to display Hello, world! on the screen somewhere. In this way, the statement does something. However, the statement doesn't actually produce any direct result. We can't try to grab the result produced from the statement, because there simply isn't one. Overall, statements are directives which have no real response.

Types of Values in Java

A non-exhaustive list of the available types in Java follows:

Punctuation in Java

Compared to natural languages, Java has quite a bit of punctuation. Two non-comprehensive lists of punctuation follow. These lists are divided into punctuation marks which are standalone, and punctuation marks which work in pairs.

Standalone Punctuation Marks

Punctuation Marks Which Work in Pairs

Comments

Comments allow for programmers to embed messages to each other directly in the source code itself. Comments are completely ignored by the compiler; comments are purely for humans reading each other's code. Comments are useful for helping other programmers understand the purpose and high-level meaning behind your code. To better understand this, consider the following code:

f = c * (9 / 5) + 32;

While the above snippet is unambiguous, it's completely unclear why it's doing what it's doing, or what it's trying to accomplish. The only apparent information is that there is some arithmetic computation being performed. Now observe the same snippet with an appropriate comment:

// convert Celsius (c) to Fahrenheit (f)
f = c * (9 / 5) + 32;

With the above comment in play, it becomes much more clear as to what the above snippet is doing: it is converting temperature in Celsius to Fahrenheit, using a standard formula.

There are two types of comments: end-of-line comments, and block comments. Each of these is described below.

  1. End-of-line comments: The comment in the snippet above is an end-of-line comment. End-of-line comments begin with //. As the name suggests, everything after // on the same line is considered a comment.

  2. Block comments: Unlike end-of-line comments, block comments can span multiple lines. Block comments begin with /*, and end with */. To see a block comment in action, consider the following code:

    x = 5;
    /* This is a block comment.
     * This comment is still going.
     * Aaaaand we're done on the next line.
     */
    y = 6;
    

    In the snippet above, everything between the /* and */ is a comment. Additionally, the comment above was aligned so that the two endpoints visually overlapped vertically, and an asterisk (*) was put at the beginning of each new line to visually help show that each of these lines was part of the same block comment. To be clear, such niceties are not required by the compiler, though they can greatly help improve readability by other programmers. Since comments are intended for other programmers anyway, it is good practice to go through this extra bit of formatting.

Indentation

Proper indentation is important for readability of your code. For example, consider the following poorly indented code:

public class Foo {
public static void main(String[] args) {  
if (3 < 2) {
System.out.println("yup");
} else {
System.out.println("nope");
}        
}
}

While the compiler will accept the above code, this is very difficult for a human to read. Generally, whenever curly braces ({}) are used to delineate some sort of body of code, this code should be indented one level in order to make it clear which bits of code match to which body. To see how this can improve readability, consider the same snippet of code below, now properly indented:

public class Foo {
  public static void main(String[] args) {  
    if (3 < 2) {
      System.out.println("yup");
    } else {
      System.out.println("nope");
    }        
  }
}

In the above snippet, it is much clearer exactly which code is the body of the “main” method, which code is underneath each branch of the if, and so on. While the above code “looks” the same to the compiler as the previous poorly-formatted snippet, this is much more appealing (and easy to read) to the human eye.