Home Formatting comments

Indentation and comments

Comments should be indented to the same level as the thing they are commenting.

Here is an example of bad indentation and commenting:

// A program that prints the number '8' using stars

public class Digit8 {
    public static void main(String[] args) {
        printLine();
        printSides();
        printLine();
        printSides();
        printLine();
    }
    
// Prints a horizontal line of 4 stars 
    public static void printLine() {
        System.out.println("****");
    }
    
// Prints two vertical lines that are 2 spaces tall, and are
// separated by 2 spaces horizontally
    public static double printSides() {
        System.out.println("*  *");
        System.out.println("*  *");
    }
}

Notice that each of the method comments are too far to the left -- they should all be indented by one level so they line up with the method:

// A program that prints the number '8' using stars

public class Digit8 {
    public static void main(String[] args) {
        printLine();
        printSides();
        printLine();
        printSides();
        printLine();
    }
    
    // Prints a horizontal line of 4 stars 
    public static void printLine() {
        System.out.println("****");
    }
    
    // Prints two vertical lines that are 2 spaces tall, and are
    // separated by 2 spaces horizontally
    public static double printSides() {
        System.out.println("*  *");
        System.out.println("*  *");
    }
}

Here is a somewhat more complex example, which uses some material from chapters 2-6 in the textbook. Note that each inline comment is placed immediately before the thing that it is commenting, and follows all of our regular indentation rules.

// A program to help me find the area of a triangle.

import java.util.*;

public class FindTriangleArea {
    // The main entry point of the program. Prompts the user to 
    // enter the three sides of the triangle, and attempts to 
    // convert it to a triangle if possible. Prints either the 
    // area or an error message to the console.
    public static void main(String[] args) {
        Scanner userInput = new Scanner(System.in);
        double sideA = prompt(userInput, "side A");
        double sideB = prompt(userInput, "side B");
        double sideC = prompt(userInput, "side C");
        
        if (isTriangle(sideA, sideB, sideC)) {
            System.out.println(computeArea(sideA, sideB, sideC));
        } else {
            System.out.println("Not a triangle");
        }
    }
    
    // Prompts the user for a double using the provided message
    public static double prompt(Scanner input, String message) {
        System.out.print(message + " ");
        return input.nextDouble();
    }
    
    // Determines if the provided side lengths form a valid triangle.
    // Returns false if any side length is non-positive, or if the side lengths
    // fail the triangle inequality theorem.
    public static boolean isTriangle(double sideA, double sideB, double sideC) {
        // all sides must be positive
        if (sideA <= 0 || sideB <= 0 || sideC <= 0) {
            return false;
        }
        
        double smallest = Math.min(sideA, Math.min(sideB, sideC));
        double largest = Math.max(sideA, Math.max(sideB, sideC));
        double middle = sideA + sideB + sideC - smallest - largest;
        
        // The triangle inequality theorem states that any side of a triangle
        // is shorter then the sum of the other two sides.
        if (smallest + middle <= largest) {
            return false;
        }
    }
    
    // Finds the area of a triangle given the side lengths.
    // Assumes the side lengths form a valid triangle (see isTriangle for criteria)
    public static double computeArea(double sideA, double sideB, double sideC) {
        // Currently using Heron's formula
        double s = 0.5 * (sideA + sideB + sideC);
        double area = Math.sqrt(s * (s - sideA) * (s - sideB) * (s - sideC));
        
        return area;
    }
}