# Getting Started

Welcome to the team! This guide helps you get up to speed with the codebase quickly.

## What This Project Does

This is a lightweight Java project in the `com.example` package that centers around an `OrderService` class with a `run()` method. It demonstrates a small order management service paired with a distributed test suite spanning multiple directories and test frameworks (JUnit 4, TestNG, and legacy JUnit 3). The project is intentionally small — it serves as a demonstration or scaffold for understanding testing strategies and source layout patterns.

## Recommended Reading Order

New engineers should read through the project in this sequence:

1. **`src/main/java/com/example/OrderService.java`** — The core production class. It's the smallest entry point and the entire production surface in a single method.
2. **`src/test/java/com/example/OrderServiceTest.java`** — The canonical unit test for `OrderService`. Shows how the service is exercised using JUnit.
3. **`src/main/java/com/example/TestHelper.java`** — The shared utility class (currently a placeholder).
4. **`standalone/OrderServiceTest.java`** — A standalone test copy for comparison. Highlights differences in test organization.
5. **`src/main/java/com/example/RogueTestAnnotated.java`**, **`src/main/java/com/example/TestNGTest.java`**, and **`src/main/java/com/example/LegacyTest.java`** — Test-like classes in the main source directory. Review these to understand why test code lives outside `src/test`.
6. **`src/utils/ImportOnlyTest.java`** and **`src/test/java/com/example/UnannotatedInTest.java`** — The remaining classes that round out the project picture.

## Key Entry Points

These are the most important classes to understand first:

- **[OrderService](src/main/java/com/example/OrderService.java)** — The primary production class. A minimal service with a single `run()` method. All other classes either test or relate to this one.
- **[OrderServiceTest](src/test/java/com/example/OrderServiceTest.java)** — The main JUnit test that exercises `OrderService`. This is the canonical test and the best entry point for understanding expected behavior.
- **[LegacyTest](src/main/java/com/example/LegacyTest.java)** — Extends `junit.framework.TestCase` (JUnit 3 style). Worth reviewing to understand the project's legacy testing patterns.
- **[TestNGTest](src/main/java/com/example/TestNGTest.java)** — Uses TestNG's `@Test` annotation, showing an alternative testing framework in use.

## Project Structure

The project follows a Maven-style directory layout, but with an important twist: test classes are scattered across multiple directories rather than living exclusively in `src/test`.

```
src/main/java/com/example/
  OrderService.java          # Production code — the core service
  LegacyTest.java            # Legacy JUnit 3 test (unusual placement)
  RogueTestAnnotated.java    # JUnit 4 annotated test in main source
  TestNGTest.java            # TestNG test in main source
  TestHelper.java            # Empty utility / scaffolding artifact

src/test/java/com/example/
  OrderServiceTest.java      # Canonical JUnit unit test
  UnannotatedInTest.java     # Unannotated test / helper class

src/utils/
  ImportOnlyTest.java        # Utility class with only an import

standalone/
  OrderServiceTest.java      # Standalone JUnit test copy (non-Maven layout)
```

**Key structural notes:**

- `src/main/` holds both production code and several test-like classes, which is non-standard and worth investigating.
- `src/test/` contains the canonical unit tests in the expected Maven location.
- `src/utils/` and `standalone/` are non-standard directories housing additional test classes in separate packages.

## Technology Stack

| Technology | Usage |
|---|---|
| **Java** | Core language for all source files |
| **JUnit 4** (`org.junit.Test`) | Unit testing framework — used by `OrderServiceTest` and `RogueTestAnnotated` |
| **TestNG** (`org.testng.annotations.Test`) | Alternative framework — used by `TestNGTest` |
| **JUnit 3** (`junit.framework.TestCase`) | Legacy style — used by `LegacyTest` |

No application frameworks (Spring, Hibernate, etc.) are used. This is a pure Java project with minimal dependencies — just the two testing libraries.

## Configuration

- **No `pom.xml` or `build.gradle` detected** — The build configuration may be managed externally or is intentionally omitted from the source tree. Check with your team for the build and test execution instructions.
- **No application config files detected** — This is a small demonstration project without externalized configuration.
- **Source layout conventions** — Test classes in `src/main` should be investigated; they may indicate a migration artifact or a specific tooling requirement.

## Common Patterns

### Minimal class design

Every class in this project is intentionally small. `OrderService` has a single method. `TestHelper` is a placeholder. The project follows a "small classes, clear purpose" philosophy.

### Multi-framework testing

The project demonstrates three testing paradigms side by side:
- JUnit 4 annotations (`@Test`)
- TestNG annotations (`@Test`)
- JUnit 3 inheritance (`extends TestCase`)

This pattern suggests the project may be used for testing tooling, static analysis, or teaching purposes.

### Test code in main source

Several test classes (`RogueTestAnnotated`, `TestNGTest`, `LegacyTest`) live in `src/main` rather than `src/test`. This is atypical and may exist for:
- Migration from an older build setup
- Demonstrating how analysis tools handle mixed placement
- A specific tooling experiment

When writing new code, prefer canonical placement: production code in `src/main`, tests in `src/test`.

### Quick start checklist

- [ ] Read `OrderService.java` and `OrderServiceTest.java` first — these two files capture the entire behavior of the project
- [ ] Run the tests with your build tool to verify the environment is set up correctly
- [ ] Check if there is a `README.md` or build configuration file (`pom.xml`, `build.gradle`) for run instructions
- [ ] Review the scattered test classes to understand the project's testing philosophy