In the previous lesson you wrote HelloBiblioTech.java and ran it, but you did so by copying a structure without understanding it. That "I write a magic spell and it works" feeling is uncomfortable and, above all, it blocks progress: when something breaks you will not know where to look. This lesson dissects a Java file word by word: what a package is, what an import is for, what each term in public static void main(String[] args) means, how statements are separated, how code is commented, which naming conventions the whole community follows and, very importantly, how to read compiler messages so that you never get stuck.

1. Full anatomy of a Java file
2. The package declaration
3. Imports
4. The class declaration
5. The main method, word by word
6. Statements, blocks and semicolons
7. Comments: line, block and Javadoc
8. Naming conventions
9. Indentation and style
10. Packages and directories in practice
11. Command-line arguments: args
12. Typical compilation errors and how to read them
13. Common Mistakes and Tips
14. Exercises

Let's start with the map. This is a complete Java file with all its parts, exactly as the start of BiblioTech will look:

The order of these parts is not optional: if there is a package declaration, it comes first; then the imports; then the class. Swapping the order is a compilation error.

A package is a namespace: it groups related classes and prevents collisions. If two different libraries define a Book class, without packages it would be impossible to use both; with packages they are com.nexussoftware.bibliotech.Book and com.othercompany.Book, and there is no ambiguity.

The concrete rules:

• It must be the first code statement in the file (only comments may precede it).
• There can be only one per file.
• It is written entirely in lowercase, with dots separating levels.
• By convention the organisation's domain reversed is used: Nexus Software would own nexussoftware.com, so its packages start with com.nexussoftware. Then the project name is appended: com.nexussoftware.bibliotech.

If you leave out the declaration, the class ends up in the default package (unnamed). It works for quick tests, but it is discouraged in any real code: classes in the default package cannot be imported from other packages, which stops the project from growing. In this module you will see both forms; from module 3 onwards, when BiblioTech has several classes, we will always use an explicit package.

An import tells the compiler where to find a class you are going to use, so that you can write Scanner instead of the full name java.util.Scanner every time.

It is important to understand what it does not do: an import does not copy code, nor increase the size of the program, nor slow it down. It is purely a writing convenience. These two versions are equivalent:

Variants:

Why have you never needed to import String or System? Because the java.lang package is imported automatically into every Java file. It contains the most basic things: String, System, Math, Integer, Object, Exception. Everything else has to be imported.

IDEs manage imports for you (IntelliJ adds them as you type the class name; Ctrl+Alt+O removes the redundant ones), but it is worth knowing what is going on.

In Java, all executable code lives inside a class. There are no free-standing file-level functions as in Python or JavaScript. Even though in this module the class is only a container for main, from module 3 onwards you will see its true purpose: grouping data and behaviour.

Let's dissect the line:

• public is an access modifier: it says the class is visible from any other package. The alternative is to write nothing (package visibility). Access modifiers are studied in depth in lesson 03-07.
• class is the reserved word that declares a class.
• BiblioTechApp is the name. It must start with a letter, $ or _ (in practice, always a letter) and it cannot be a reserved word of the language.
• { ... } delimit the body of the class. Everything belonging to the class goes inside.

The file-name rule, already mentioned: if the class is public, the file must be named exactly like it plus .java. public class BiblioTechApp → BiblioTechApp.java. Java is case-sensitive, so bibliotechapp.java will not do. A file may contain several classes, but only one of them can be public.

This signature is a contract with the JVM. When you run java BiblioTechApp, the virtual machine looks in that class for a method with exactly this shape. If it differs in any detail, it will not start. Let's analyse each term:

Details that often come as a surprise:

• The parameter name can change: String[] arguments is equally valid. What cannot change is its type.
• String[] args and String args[] are equivalent; the first form is the modern convention.
• Since Java 21 you can write void main() without modifiers in single-file programs (a preview feature designed for learning). This course uses the full standard form, which is what you will find in all professional code.
• You may write static public void main(...): the order of the modifiers is free. The convention is public static.

If you get the signature wrong, the program compiles just fine (it is a valid method, it simply is not the main), but when you run it you get:

That is, a runtime error, not a compilation error. Remembering this will save you some confusion.

A statement is a complete instruction. In Java every statement ends with a semicolon:

A block is a set of statements between braces { }. Blocks define the body of classes and methods, and later on that of conditionals and loops.

The rule that clears up 90 % of the doubts: braces are not followed by a semicolon.

Java is a free-format language: line breaks and spaces do not change the meaning, only the readability. These three versions compile identically:

The fact that the compiler accepts all three does not mean they are worth the same: code is read many more times than it is written.

Comments are text the compiler ignores. Java has three forms and each has its place:

Javadoc is more than a pretty comment: the javadoc tool included in the JDK generates a documentation website from them, and IDEs show them as contextual help when you hover over a class. The official Java API documentation is generated exactly like that. Its most used tags are @param (describes a parameter), @return (describes the returned value) and @author. In this module you will barely use them because you only have main, but from module 3 onwards they will be routine.

A tip about good comments: do not explain what the code does if the code already says it; explain why.

Java does not force you to follow them: the compiler accepts class biblio_tech_app. But the Java community is exceptionally uniform on this point, and ignoring the conventions immediately marks code as amateur. They also have functional value: they tell you at a glance what kind of element you are looking at.

Why they really matter:

• When you read Book book = ... you know without thinking that Book is a type and book a variable. The convention removes the ambiguity.
• When you see DAILY_RATE you know it is a value that does not change, without going to look at its declaration.
• IDEs, static analysers and code generation tools all assume them.

Additional rules about names:

• They must start with a letter, _ or $. Never with a digit.
• They may contain letters, digits, _ and $. Java accepts accented letters and ñ because it supports Unicode, but avoid them: they cause encoding problems between systems. Stick to plain ASCII: write publicationYear, not añoPublicación.
• They cannot be reserved words (class, int, public, static, new, return…).
• They are case-sensitive: title, Title and TITLE are three different identifiers.
• Use descriptive names. daysLate is infinitely better than d or x. A variable's name is the most-read documentation in the code.

Indentation does not affect compilation, but it is the first thing that separates readable code from unreadable code. The dominant conventions in Java:

• Four spaces per nesting level (not tabs; configure it in your IDE).
• Opening brace at the end of the line, not on its own line. It is the official Java style and it differs from the usual C# one.
• One space around operators: int total = a + b;, not int total=a+b;.
• Lines of reasonable length (100-120 characters at most).
• A blank line to separate logical blocks.

Every IDE reformats automatically: in IntelliJ it is Ctrl+Alt+L, in Eclipse Ctrl+Shift+F, in VS Code Shift+Alt+F. Get into the habit of pressing it before you consider a file finished.

Here is a strict rule that causes many errors for beginners: the package hierarchy must match the directory hierarchy.

If your file declares:

then BiblioTechApp.java must live at .../com/nexussoftware/bibliotech/BiblioTechApp.java.

And this changes how you compile and run from the terminal. Standing in src/main/java:

Notice the essential difference: when compiling you use slashes (it is a file path); when running you use dots (it is a class name). Typing plain java BiblioTechApp when the class is in a package produces Could not find or load main class, because the class's real name includes its package.

A practical option to keep the .class files out of your source code:

• -d indicates the output directory for the .class files, and javac recreates the package structure there automatically.
• -cp (classpath) tells the java command where to look for the classes.

When you work in the IDE it handles all of this for you; but when something breaks, you will know what it is doing underneath.

The String[] args parameter receives the values you type after the class name when running. It is the simplest way to pass data to a program.

Running it:

Output:

Key points:

• Arguments are separated by spaces. If a value contains spaces (like Effective Java), it has to be wrapped in quotes; otherwise it would arrive as two separate arguments.
• They always arrive as String, even if you type a number. java Program 2018 makes args[0] the text "2018", not the number. To convert it you use Integer.parseInt(args[0]), which you will see in lesson 01-04.
• The index starts at 0: the first argument is args[0].
• If you access an index that does not exist (for example args[1] when you only passed one), the program fails at runtime with ArrayIndexOutOfBoundsException. Checking args.length first requires conditionals, which arrive in module 2; handling the error, in module 6.
• The class name is not part of args, unlike what happens in C.

They can also be configured in IDEs: in IntelliJ, Run → Edit Configurations… → Program arguments.

Learning to read javac messages is a skill that pays for itself. The format is always the same:

Let's look at the four most frequent ones and their diagnosis.

Diagnosis: a semicolon is missing. An important warning: the compiler points at the end of the line before the problem, so if the error seems to make no sense on the line indicated, look at the line above.

Diagnosis: the compiler does not know that name. The three causes, by frequency: (1) you have not declared it; (2) you typed it with different capitalisation (Title vs title); (3) a class import is missing.

Diagnosis: Java's static typing in action. You are putting a value of one type into a variable of another. It is exactly the kind of error that in a dynamic language would blow up in production.

Diagnosis: the file name does not match the public class name. Rename one of the two.

This is a fundamental distinction:

A tip on method: when javac reports twenty errors, fix only the first one and compile again. A single mistake (an unclosed brace, for instance) triggers a cascade of derived errors that disappear on their own.

• Putting a semicolon after the closing brace of a method or class. It is not a serious error (Java tolerates it as an empty statement in some contexts), but it betrays inexperience and in other places it does cause an error.
• Writing Main instead of main. Java is case-sensitive: it compiles, but at runtime it says Main method not found.
• Forgetting that the public class and the file must have the same name.
• Putting the import before the package. The order is fixed: package, then import, then the class.
• Running java BiblioTechApp when the class is in a package. You have to use the fully qualified name: java com.nexussoftware.bibliotech.BiblioTechApp.
• Trusting the error's line number without looking at the previous one. Very typical with ';' expected.
• Tip: configure your IDE to format on save. You will never argue about style and your code will be uniform from day one.
• Tip: when you copy code from the internet, type it out. The mistakes you make and fix are the real learning.
• Tip: unbalanced braces are the most frequent cause of incomprehensible errors. Every IDE highlights the matching brace when you place the cursor on one: use it.

The following file, saved as BiblioTechApp.java, contains five errors. Find them, explain why they are errors and write the corrected version.

Create the class BiblioTechCard inside the package com.nexussoftware.bibliotech, with the correct directory structure. The program must receive a book's title and ISBN from the command line and show them under a header. Include a Javadoc comment on the class and a line comment explaining where the data comes from. Also write the exact compilation and execution commands.

Expected run:

Output:

The following code compiles perfectly, but it breaks every Java convention. Rewrite it applying them and justify each change.

Solution 1

The five errors:

1. import before package. The package declaration must be the first statement in the file.
2. class bibliotechApp does not match the file name BiblioTechApp.java. It also breaks PascalCase.
3. Main instead of main. With a capital letter it is not the entry point; the program would compile but fail at runtime with Main method not found.
4. String args instead of String[] args. The parameter must be an array of strings; without the brackets, the signature is not the one the JVM looks for.
5. The semicolon is missing at the end of the first println. And there is a sixth, knock-on problem: Title is not declared anywhere, which would produce cannot find symbol.

Corrected version:

Note: if in the end you do not use Scanner, the right thing to do is remove its import. An unused import is not an error, but it is noise.

Solution 2

Directory structure, starting from the project root:

The file:

The commands, standing in src/main/java:

An important detail: "Design Patterns" goes in quotes because it contains a space. Without them, the system would pass two arguments (Design, Patterns) and the output would be wrong.

Solution 3

Justification for each change:

There are no magic spells left: you know that a Java file is arranged as package, import and class; that public static void main(String[] args) is a contract with the JVM and what each word contributes; that statements end with a semicolon and braces do not; that there are three kinds of comment and that Javadoc generates real documentation; that naming conventions communicate information at a glance; that packages correspond to directories and that this changes how you compile and run; that args brings command-line arguments always as text; and, above all, how to read a compiler error message instead of freezing in front of it.

In the next lesson, Variables and Data Types, we will fill that skeleton with content: the eight primitive types with their ranges, literals, the difference between primitive and reference types, String and its immutability, type conversions, constants with final and inference with var. By the end of it you will be able to model a complete book from the BiblioTech catalog using variables.