Dr. T's Style Guide

Introduction

"Even if you don’t intend anybody else to read your code, there’s still a very good chance that somebody will have to stare at your code and figure out what it does: That person is probably going to be you, twelve months from now."

— Raymond Chen, Microsoft Developer

Programming is a form of creative expression. While the primary goal of any code is to solve a problem, the way you express the solution is often more important than the solution itself. Code can be beautiful when written clearly and elegantly. For inspiration, read “10 PRINT CHR$(205.5+RND(1)); : GOTO 10” by Montfort et al., and “If Hemingway Wrote JavaScript” by Angus Croll.

This document contains best practices for my students, influenced by Python’s PEP-8 style guide, but adapted for Java. Writing clear and maintainable code isn't just a good habit—it’s a professional standard.

Comment Your Code

No matter how experienced you are, you are not too good to comment your code. Well-commented code is key to readability and maintainability.

Prologue Comments

The prologue is an introductory block of comments at the top of your file. It should include:

• Program name
• Author name
• Course title
• Date
• Assignment number
• Program description

Use the following format for your prologue in Java:

/**
 * Program Name: HelloWorld.java
 * Author: Trevor M. Tomesh
 * Course: CS 427
 * Date: 2023/02/16
 * Assignment #1
 *
 * Description:
 * This program demonstrates the basic structure and style guidelines
 * for a simple Java program.
 */

Explaining Code

Comments should explain what the code is trying to accomplish, not just restate the code. Comments that simply rephrase code lines are redundant and unhelpful. Instead, your comments should clarify intent and provide context, especially when algorithms or logic may not be immediately clear to the reader.

For example, when implementing Euler’s method for numerical integration:

Good:

/**
 * Computes the solution of a function using Euler's method.
 * This method is used to approximate solutions of ordinary
 * differential equations (ODEs).
 */
while (x <= t) {
    double k = h * function(x, y);  // Calculate the slope (k)
    y += k;                         // Update y based on the slope
    x += h;                         // Move x forward by step size h
    System.out.printf("%.3f\t%.3f\n", x, y);  // Print the new x and y values
}

Bad:

while (x <= t) { // while loop
    double k = h * function(x, y); // multiply h with function(x, y)
    y += k; // add k to y
    x += h; // increment x by h
    System.out.printf("%.3f\t%.3f\n", x, y); // print x and y
}

Comments in the bad example merely repeat what the code is doing rather than offering insight into why it's doing it or what purpose it serves.

Documenting Methods and Functions

Each method and function should have a JavaDoc comment that clearly describes its purpose, the role of each parameter, and the expected return value (if any). This documentation should be concise but complete.

Why is this important? Well-documented methods help others (and your future self) quickly understand how to use a function without needing to read through the implementation details.

Example of a well-documented method:

/**
 * Calculates the sum of two integers.
 * This method adds two integers and returns their sum.
 *
 * @param a the first integer
 * @param b the second integer
 * @return the sum of a and b
 */
public static int sum(int a, int b) {
    return a + b;
}

Note how the comment explains the role of each parameter and the function's output. JavaDoc comments also provide valuable information when generating documentation automatically.

Group Your Functions

Functions and methods that are logically related should be grouped together. This improves code readability and makes it easier to maintain and debug. For instance, keep all arithmetic operations together, and separate utility functions from core logic.

//---------------------
// Arithmetic Operations
//---------------------

/**
 * Calculates the sum of two integers.
 *
 * @param a the first integer
 * @param b the second integer
 * @return the sum of a and b
 */
public static int sum(int a, int b) {
    return a + b;
}

/**
 * Calculates the difference between two integers.
 *
 * @param a the first integer
 * @param b the second integer
 * @return the difference of a and b
 */
public static int diff(int a, int b) {
    return a - b;
}

By grouping related methods, you make it easier for someone reading your code to find and understand related functionalities. This organization also helps when extending or modifying code.

Naming, Spacing, and Layout

Indentation

Proper indentation is crucial for readability. In Java, use 4 spaces per indentation level. Avoid using tabs, as they can display inconsistently across different editors and environments.

Good example:

for (int i = 0; i < 100; i++) {
    if (i == 42) {
        System.out.println("Life, the universe, whatever...");
    } else {
        System.out.println(i);
    }
}

Bad example:

for(int i=0;i<100;i++){if(i==42){System.out.println("Life, the universe, whatever...");}else{System.out.println(i);}}

Line Length

Limit line lengths to 80 characters max to enhance readability, especially on smaller screens or when working with multiple code windows. Long lines can be split into multiple lines for clarity.

System.out.println("This is a very long statement that goes over " +
                   "80 characters, so we split it into multiple lines.");

Keeping lines short makes your code easier to read and understand, improving maintainability and debugging efficiency.