Package Naming and Folder Structure

Two companies might both write a class called Account. When your program uses libraries from both, Java needs a way to tell them apart. The convention is simple and global: start the package name with your organization's internet domain, reversed. Domain names are already unique worldwide, so package names built from them are unique too. The name then maps directly onto folders on disk.

Naming Rules and Conventions

Breaking the identifier rules is a compile error:

package com.my-site.app;
class Hy {}

Hy.java:1: error: ';' expected
package com.my-site.app;
              ^
1 error

package com.poolstring.new.util;
class Kw {}

Kw.java:1: error: <identifier> expected
package com.poolstring.new.util;
                       ^
1 error

Names Map to Folders

Each dot-separated part is one folder. The source folder (src) is the root, and the output folder (out) mirrors the same tree:

bank/
├── src/
│   └── com/poolstring/bank/
│       ├── app/BankApp.java              package com.poolstring.bank.app;
│       ├── model/Account.java            package com.poolstring.bank.model;
│       └── service/TransferService.java  package com.poolstring.bank.service;
└── out/
    └── com/poolstring/bank/
        ├── app/BankApp.class
        ├── model/Account.class
        └── service/TransferService.class

Build tools use a slightly longer standard layout: src/main/java for code, src/test/java for tests, and src/main/resources for other files. The package folders start inside those.

When the Folder Doesn't Match

If Account.java declares package com.poolstring.bank.model; but sits directly in src/, the compiler can't find it when another class imports it, because it looks in the folder the package name points to:

javac -d out -sourcepath src src/com/poolstring/bank/app/BankApp.java

src/com/poolstring/bank/app/BankApp.java:3: error: package com.poolstring.bank.model does not exist
import com.poolstring.bank.model.Account;
                                ^

-sourcepath src tells javac to look up other source files by package. Moving Account.java into src/com/poolstring/bank/model/ fixes it. IDEs flag the mismatch as soon as you open the file.

Common Mistakes

Uppercase letters in package names. It compiles, but it breaks convention and can confuse case-insensitive file systems.

Hyphens from a domain name. Replace them with underscores: my-site.com becomes com.my_site.

Moving a file without changing its package line (or the other way round). Keep them in sync; IDE refactoring does both together.

Practice

1. Easy: Write package names for a project called "library" at the domain navika-books.in, with packages for books, members and loans.
2. Harder: Deliberately put TransferService.java in the wrong folder, compile BankApp with -sourcepath src, read the error, then fix it.

Key Takeaways