# Getting Started

## What This Project Does

This repository is a lightweight Java project consisting of a handful of single-class source files, each illustrating a distinct pattern for placing headers — Javadoc blocks, license notices, version history — at the top of a Java source file. It serves as a demo or test codebase for studying header conventions, not as a production application.

There are no external dependencies, no build system files, and no runnable entry point. The entire codebase is small enough to read end-to-end in a few minutes.

## Recommended Reading Order

Follow this sequence to build your understanding incrementally, starting from the simplest file and moving toward the more complex:

1. **[NoHeader.java](src/main/java/NoHeader.java)** — The control case: no header at all, just a bare class declaration. 3 lines.
2. **[WithHeader.java](src/main/java/WithHeader.java)** — A standard, idiomatic Javadoc-style header with a processing name and version.
3. **[MitLicense.java](src/main/java/MitLicense.java)** — A minimal MIT License header demonstrating concise copyright placement.
4. **[PartialHeader.java](src/main/java/PartialHeader.java)** — A Javadoc block with module name and function summary fields but no version history line.
5. **[Crosslink.java](src/main/java/Crosslink.java)** — A header with versioned inline code sections marked by `ADD START` / `ADD END` comments, showing a pattern for tracking incremental additions.
6. **[LongHeader.java](src/main/java/LongHeader.java)** — The most distinctive file: a 250+ line Javadoc header recording a version bump with a ticket number and author on every line. Included as an example of how *not* to do versioning in practice.

```mermaid
flowchart LR
    A["NoHeader"] --> B["WithHeader"]
    B --> C["MitLicense"]
    C --> D["PartialHeader"]
    D --> E["Crosslink"]
    E --> F["LongHeader"]
```

## Key Entry Points

All six classes are independent and have no dependencies on each other. Start with these two:

- **NoHeader** (`NoHeader.java`) — The simplest file. Read this first to understand the baseline before adding any header structure.
- **WithHeader** (`WithHeader.java`) — The most conventional header format in Java. Use this as your reference for idiomatic Javadoc headers.

After those, skim **MitLicense** for a real-world license pattern, then **PartialHeader** and **Crosslink** for variations. End with **LongHeader** to see an extreme (and likely cautionary) example of embedding extensive version history directly in source files.

## Project Structure

The repository has a flat, single-module layout. There are no packages, sub-modules, or layered architecture:

```
root/
  src/main/java/
    Crosslink.java      — Header with versioned inline code markers
    LongHeader.java     — Extended 250+ line version history header
    MitLicense.java     — Minimal MIT License header
    NoHeader.java       — Bare class, no header (control case)
    PartialHeader.java  — Partial Javadoc header (module + summary)
    WithHeader.java     — Standard Javadoc-style header
```

Each `.java` file is a standalone `public class` with no imports beyond the Java standard library and no methods beyond what the language implicitly provides (e.g., a default constructor). The only distinguishing feature between files is their header — the block comment at the top of the file.

```mermaid
flowchart TD
    A["src/main/java/"] --> B["NoHeader"]
    A --> C["WithHeader"]
    A --> D["PartialHeader"]
    A --> E["Crosslink"]
    A --> F["MitLicense"]
    A --> G["LongHeader"]

    B["NoHeader"] --> H["No header at all"]
    C["WithHeader"] --> I["Standard header format"]
    D["PartialHeader"] --> J["Partial Javadoc block"]
    E["Crosslink"] --> K["Inline version markers"]
    F["MitLicense"] --> L["MIT License header"]
    G["LongHeader"] --> M["250+ line version history"]
```

## Configuration

This repository has no build files, no dependency declarations, and no runtime configuration:

- **No `pom.xml`, `build.gradle`, or `settings.xml`** — there is no build system.
- **No `application.properties`, `.env`, or YAML configs** — the code has no runtime behavior.
- **No `package-info.java` or module declarations** — classes are in the default (unnamed) package.

You can compile any single file directly with `javac` if you want to verify it compiles:

```bash
javac src/main/java/NoHeader.java
javac src/main/java/WithHeader.java
javac src/main/java/LongHeader.java
```

The only "configuration" worth knowing is the directory layout itself: all source lives in `src/main/java/` at the repository root with no sub-packages.

## Common Patterns

### Header Styles

The project catalogs six header patterns side by side for comparison:

| File | Header Type | Purpose |
|------|------------|---------|
| `NoHeader.java` | None | Baseline / control |
| `WithHeader.java` | Standard Javadoc | Conventional approach |
| `MitLicense.java` | MIT License | Concise copyright notice |
| `PartialHeader.java` | Partial Javadoc | Module + summary, no version history |
| `Crosslink.java` | Javadoc + inline markers | `ADD START` / `ADD END` code sections |
| `LongHeader.java` | Extended Javadoc | Extensive version history (cautionary) |

### Code Conventions

- **Single class per file** — Every `.java` file contains exactly one `public class`.
- **No packages** — All classes live in the default package.
- **No inter-class dependencies** — Classes are self-contained; none import or reference each other.
- **Header-only differentiation** — The files differ only in their Javadoc block; the class bodies are minimal (effectively empty).

### What to Avoid (Learned from LongHeader.java)

`LongHeader.java` embeds over 250 lines of version history inside the source file itself — one entry per version bump, each with a ticket number and author. This pattern:

- Makes the file difficult to read and navigate
- Creates enormous diffs for trivial version bumps
- Duplicates information that version control systems already track

Use your VCS's commit history and changelogs instead of embedding version data in source headers.