Java Program Structure Explained — Every Part, Every Line, Every Reason

// LAYER 1: Package declaration — tells Java which 'folder' this class lives in.
// Think of it as the return address on an envelope.
// Optional for tiny programs, but always used in real projects.
package com.thecodeforge.basics;

// LAYER 2: Import statements — bring in pre-built Java tools you want to use.
// This line says: 'I want to use Java's Scanner tool in my code.'
import java.util.Scanner;

// LAYER 3: Class declaration — the outer container for all your code.
// The filename MUST match the class name exactly: ProgramStructureMap.java
public class ProgramStructureMap {

    // LAYER 4: Field — a variable that belongs to the whole class.
    // This one stores the name of our application.
    private static String applicationName = "Structure Explorer";

    // LAYER 4 (continued): Method — a named block of instructions.
    // 'main' is the special method Java looks for to START the program.
    // The signature must be EXACTLY: public static void main(String[] args)
    public static void main(String[] args) {

        // LAYER 5: Statements — the actual instructions that execute line by line.
        // Each statement ends with a semicolon — the full stop of Java.
        System.out.println("Application: " + applicationName);
        System.out.println("--- Layers of this program ---");
        System.out.println("Layer 1: Package  -> com.thecodeforge.basics");
        System.out.println("Layer 2: Import   -> java.util.Scanner (loaded, ready)");
        System.out.println("Layer 3: Class    -> ProgramStructureMap");
        System.out.println("Layer 4: Method   -> main");
        System.out.println("Layer 5: This println is a statement inside main");

    } // end of main method

} // end of class ProgramStructureMap

// No package needed for this standalone demo — fine for learning.

public class MainMethodExplained {

    /*
     * Let's prove that 'args' actually captures command-line input.
     * To test this, compile and run with:
     *   javac MainMethodExplained.java
     *   java MainMethodExplained Alice 30
     * 'Alice' lands in args[0], '30' lands in args[1].
     */
    public static void main(String[] args) {

        // Check how many arguments the user passed in from the terminal.
        // args.length tells us the count — like asking how many items in a bag.
        System.out.println("Number of arguments received: " + args.length);

        // If the user passed at least two arguments, use them.
        // Otherwise, print a friendly default message.
        if (args.length >= 2) {
            // args[0] is the first argument, args[1] is the second.
            String userName = args[0];
            String userAge  = args[1];
            System.out.println("Hello, " + userName + "! You said you are " + userAge + " years old.");
        } else {
            // No arguments provided — greet with a default message.
            System.out.println("Hello, anonymous! Pass your name and age as arguments next time.");
        }

        // This line always runs, regardless of arguments.
        System.out.println("Main method complete. Program exits now.");

    } // The closing brace ends the main method.

} // The closing brace ends the class.

// Package declaration — this file must live in src/com/thecodeforge/demo/
// In real projects, this mirrors your company/project domain reversed.
package com.thecodeforge.demo;

// Import a specific class from Java's utility library.
// ArrayList is a resizable list — we'll use it to store student names.
import java.util.ArrayList;

// Import Java's LocalDate class to show today's date.
// This lives in java.time package — added in Java 8.
import java.time.LocalDate;

// We do NOT need to import String or System — they're in java.lang,
// which Java imports automatically for every program.

public class PackageAndImportDemo {

    public static void main(String[] args) {

        // LocalDate.now() asks the system for today's date.
        // Because we imported java.time.LocalDate, we don't need the full path.
        LocalDate todayDate = LocalDate.now();
        System.out.println("Program running on: " + todayDate);

        // Create a new ArrayList to hold student name strings.
        // Without the import above, we'd have to write:
        // java.util.ArrayList<String> studentNames = new java.util.ArrayList<>();
        ArrayList<String> studentNames = new ArrayList<>();

        // Add three student names to the list.
        studentNames.add("Maria Santos");
        studentNames.add("James Okafor");
        studentNames.add("Priya Sharma");

        System.out.println("Enrolled students:");

        // Loop through each name and print it.
        // The 'for-each' loop reads: 'for each name in studentNames, print it'.
        for (String name : studentNames) {
            System.out.println("  -> " + name);
        }

        System.out.println("Total enrolled: " + studentNames.size());

    }

}

// Layer 1: Package — organises this class inside a 'school' sub-project.
package com.thecodeforge.school;

// Layer 2: Import — we need Scanner to read user input from the keyboard.
import java.util.Scanner;

// Layer 3: Class — the container. Filename must be GradeCalculator.java.
public class GradeCalculator {

    // Layer 4: Constant field — belongs to the class, not to any method.
    // 'static final' means it's shared and never changes — a true constant.
    // Convention: constants use ALL_CAPS with underscores.
    private static final double PASSING_SCORE = 50.0;

    // Layer 4: The main method — JVM starts here.
    public static void main(String[] args) {

        // Create a Scanner that reads from System.in — the keyboard.
        Scanner keyboardInput = new Scanner(System.in);

        System.out.println("=== Grade Calculator ===");
        System.out.print("Enter student name: ");

        // nextLine() reads a full line of text the user types, including spaces.
        String studentName = keyboardInput.nextLine();

        System.out.print("Enter score (0-100): ");

        // nextDouble() reads a decimal number from the keyboard.
        double studentScore = keyboardInput.nextDouble();

        // Determine if the student passed, using the class-level constant.
        boolean hasPassed = studentScore >= PASSING_SCORE;

        // Call our helper method to convert the numeric score to a letter grade.
        // This method is defined below — Java finds it inside the same class.
        String letterGrade = calculateLetterGrade(studentScore);

        // Print the full result summary.
        System.out.println("\n--- Result for " + studentName + " ---");
        System.out.println("Score:        " + studentScore);
        System.out.println("Letter Grade: " + letterGrade);
        System.out.println("Status:       " + (hasPassed ? "PASSED" : "FAILED"));

        // Always close a Scanner when you're done — releases system resources.
        keyboardInput.close();

    } // end of main

    // Layer 4: A second method — does one specific job: score to letter conversion.
    // 'private' means only this class can call it.
    // 'static' means we can call it without creating a GradeCalculator object.
    // 'String' means it returns a String value back to whoever called it.
    private static String calculateLetterGrade(double score) {

        // Cascade from highest to lowest to find the right band.
        if (score >= 90) {
            return "A"; // return sends the value back to the caller immediately.
        } else if (score >= 80) {
            return "B";
        } else if (score >= 70) {
            return "C";
        } else if (score >= 60) {
            return "D";
        } else {
            return "F"; // Anything below 60 is a failing letter grade.
        }

    } // end of calculateLetterGrade

} // end of class GradeCalculator