Comments, keywords and naming conventions

The code nobody could read

Comments, keywords and identifiers

Words you'll meet in this lesson

Java naming conventions

Kinds of comments and keywords

Keyword groups (about 50 reserved words)

How javac reads names and comments

1. Unicode escapes are translated first

   Before anything else, javac turns \uXXXX sequences into characters, everywhere, even inside comments.

   That's why the famous trick // \u000a System.out.println("hi"); actually runs: \u000a becomes a newline, ending the comment early.

2. Comments and whitespace are removed

   The lexer skips spaces, tabs, newlines and all three kinds of comments.

   Nothing from a comment reaches the .class file. Comments cost nothing at run time, so there's no performance reason to avoid them.

3. Each word is classified

   Is it a keyword, a literal (42, "hi", true), an operator, or an identifier?

   Reserved keywords always win. int new = 5; fails because new is read as the keyword, and the grammar then doesn't make sense.

4. Identifiers are checked against the rules

   Must not start with a digit; may use letters from any language (int नाम = 7; is legal), _ and $.

   Names are stored in the class file's constant pool (for classes, methods and fields), so renaming a public method changes the bytecode other classes link to.

5. Conventions are checked by people and tools

   javac doesn't enforce PascalCase or camelCase. Code reviewers, IDE inspections and tools like Checkstyle do.

   The javadoc tool reads /** */ comments separately and generates HTML pages, like the official Java API documentation.

What javac keeps, and what it throws away: both views

Left: the source and the result. Right: how javac's lexer and the javadoc tool see it.

Names and comments in real teams

In companies, readable code is a requirement, not a preference. Here's how it's enforced and why.

Watch it with an example: a code review on a fee program

The code works but nobody can read it. Watch a reviewer fix one problem per step using Java's naming conventions.

Examples are simplified. Each team has its own style guide; many follow Google's or Oracle's Java conventions.

Riya's bill calculator, written properly

/**
 * Calculates a canteen bill.
 */
public class Main {
    static final int GST_PERCENT = 5;   // constant: UPPER_SNAKE_CASE

    public static void main(String[] args) {
        int chaiCount = 3;               // variable: camelCase
        int billAmount = calculateBill(chaiCount);
        System.out.println("Bill: Rs " + billAmount);
    }

    /** Returns the bill for the given number of cups, including GST. */
    static int calculateBill(int cups) {
        int base = cups * 20;
        return base + base * GST_PERCENT / 100;
    }
}

• /** Calculates a canteen bill. */A Javadoc comment for the class.
• GST_PERCENTA static final constant, so UPPER_SNAKE_CASE.
• chaiCount, billAmountVariables in camelCase that say what they hold.
• calculateBill(int cups)A method named with a verb, in camelCase.
• // constant: …Single-line comments. Real code should explain why, not repeat what; these are here for learning.

Comments vanish, names remain

Notice how the tracer never stops on a comment line: by the time the program runs, comments no longer exist.

Worked examples: real problems, solved and traced in memory

Good names and comments don't change what the program does; they change how fast the next person understands it. Each example is a real calculation written the way professional teams write it: clear names, constants in CAPITALS, and comments that explain why.

basic salary 30000

old: 38400.0
new: 38400.0

orders of Rs 350 and Rs 620

Rs 350 order: fee Rs 40
Rs 620 order: fee Rs 0

30 units, 180 units; Rs 6/unit; minimum Rs 250

30 units: Rs 250
180 units: Rs 1080

Check yourself

Quick revision

Interview and viva questions

Practice problems

Rewrite and write code with clear names, constants and helpful comments. The output stays the same; the code gets easier to read. The last three are business tasks.

(none)

Comments are ignored

public class Main {
    public static void main(String[] args) {
        // this line is a single-line comment
        /* this is a
           multi-line comment */
        System.out.println("Comments are ignored");
    }
}

42

Students: 42

public class Main {
    public static void main(String[] args) {
        int studentsInClass = 42;
        System.out.println("Students: " + studentsInClass);
    }
}

800

Service charge: Rs 40.0

public class Main {
    static final double SERVICE_CHARGE = 0.05;

    public static void main(String[] args) {
        System.out.println("Service charge: Rs " + 800 * SERVICE_CHARGE);
    }
}

60, 45

Total teaching minutes: 2700

public class Main {
    public static void main(String[] args) {
        int minutesPerClass = 60;
        int classesPerTerm = 45;
        int totalMinutes = minutesPerClass * classesPerTerm;
        System.out.println("Total teaching minutes: " + totalMinutes);
    }
}

2

12.566370614359172

public class Main {
    static double calculateArea(double radius) {
        return Math.PI * radius * radius;
    }

    public static void main(String[] args) {
        System.out.println(calculateArea(2));
    }
}

250, 6

Invoice total: Rs 1682

public class Main {
    static final double DISCOUNT_RATE = 0.05;
    static final double GST_RATE = 0.18;

    public static void main(String[] args) {
        double unitPrice = 250;
        int quantity = 6;
        double subtotal = unitPrice * quantity;
        double afterDiscount = subtotal * (1 - DISCOUNT_RATE);
        double invoiceTotal = afterDiscount * (1 + GST_RATE);
        System.out.println("Invoice total: Rs " + Math.round(invoiceTotal));
    }
}

14 days

Late fee: Rs 100

public class Main {
    static final int FEE_PER_DAY = 10;
    // Library rule: late fees are capped so students aren't charged more than a book's typical cost.
    static final int MAX_LATE_FEE = 100;

    public static void main(String[] args) {
        int daysLate = 14;
        int fee = Math.min(daysLate * FEE_PER_DAY, MAX_LATE_FEE);
        System.out.println("Late fee: Rs " + fee);
    }
}

(none)

Shree Traders target: Rs 500000

public class Main {
    static final String COMPANY_NAME = "Shree Traders";

    public static void main(String[] args) {
        int monthlySalesTarget = 500000;
        System.out.println(COMPANY_NAME + " target: Rs " + monthlySalesTarget);
    }
}

Real-world scenario questions (asked in company interviews)

Readability problems are maintenance problems, and maintenance is most of a developer's job. Decide your answer first, then open the model answer.