diff --git a/.claude.md b/.claude.md index f8dd964fb..a70605575 100644 --- a/.claude.md +++ b/.claude.md @@ -2,6 +2,16 @@ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +## Project Purpose + +This is an **educational algorithms and data structures repository**. The core goal is to provide clear, well-tested, and accessible implementations for learners who may not have deep computer science backgrounds. + +**Key Principles:** +- **Every file should teach**, not just implement. +- Implementations should be simple, elegant, and avoid unnecessary complexity (e.g., prefer plain loops over Java Streams). +- Documentation must explain *how* and *why* an algorithm works, including time and space complexity. +- Every algorithm must be accompanied by comprehensive tests that cover edge cases and teach through examples. + ## Build System This project uses **Bazel** as its build system (requires JDK 8+). Dependencies are managed via Maven through `rules_jvm_external` and declared in `MODULE.bazel`. diff --git a/.gemini.md b/.gemini.md deleted file mode 100644 index 61e69caa0..000000000 --- a/.gemini.md +++ /dev/null @@ -1,80 +0,0 @@ -# Gemini CLI - Algorithms & Data Structures (Java) - -This repository contains a collection of common data structures and algorithms implemented in Java, with a focus on simplicity and elegance. - -## Project Overview - -- **Main Technologies:** Java (JDK 8+), Bazel (Build System). -- **Core Goal:** Demonstrate correct and efficient implementations of algorithms. -- **Architecture:** Organized into thematic packages (e.g., `datastructures`, `graphtheory`, `dp`). -- **Dependencies:** Managed via Bazel's `MODULE.bazel` using `rules_jvm_external`. Key dependencies include JUnit 5, Guava, and Mockito. - -## Building and Running - -### Using Bazel (Recommended) - -Bazel is the primary build system. Each package contains a `BUILD` file defining libraries and binaries. - -- **Run an algorithm:** - ```bash - bazel run //src/main/java/com/williamfiset/algorithms/: - ``` - Example: `bazel run //src/main/java/com/williamfiset/algorithms/search:BinarySearch` - -- **Run all tests:** - ```bash - bazel test //src/test/... - ``` - -- **Run tests for a specific package:** - ```bash - bazel test //src/test/java/com/williamfiset/algorithms/:all - ``` - -- **Run a specific test class:** - ```bash - bazel test //src/test/java/com/williamfiset/algorithms/: - ``` - -### Using only JDK - -If Bazel is not available, you can compile and run manually: -```bash -mkdir -p classes -javac -sourcepath src/main/java -d classes src/main/java/com/williamfiset/algorithms//.java -java -cp classes com.williamfiset.algorithms.. -``` - -## Development Conventions - -### Documentation and Comments -- **Educational Context:** This repository is an educational project. Most comments (except for the most trivial ones) must be preserved during refactoring. -- **Purpose:** Comments should explain *how* and *why* an algorithm or data structure works to aid understanding for students and developers. -- **Refactoring:** When simplifying code, ensure that the conceptual explanations remain intact. - -### Project Structure -- `src/main/java/com/williamfiset/algorithms/`: Implementation source code. -- `src/test/java/com/williamfiset/algorithms/`: Unit tests (mirrors source structure). -- `utils/`: Contains helper classes like `GraphGenerator` and graph `Utils`. - -### Adding a New Algorithm -1. **Implementation:** Add the `.java` file to the appropriate package in `src/main/java/...`. -2. **Bazel Configuration:** - - Add the file to the `java_library`'s `srcs` in the package's `BUILD` file (usually handled by `glob`). - - Add a `java_binary` target for the class if it has a `main` method. -3. **Testing:** - - Create a corresponding test file in `src/test/java/...`. - - Use **JUnit 5 (Jupiter)** for new tests. - - Add a `java_test` target in the test directory's `BUILD` file. -4. **Documentation:** Update the `README.md` with a link to the new implementation and its complexity. - -### Coding Patterns -- **Solvers:** Many algorithms are implemented as "Solver" classes where you instantiate, provide input (e.g., add edges), and then call a `solve()` or specific getter method. -- **Graph Representation:** Adjacency lists are commonly represented as `List>` or `List>`. -- **Flow Algorithms:** Share a common base `NetworkFlowSolverBase`. - -## Key Files -- `README.md`: Comprehensive list of all implemented algorithms and data structures. -- `MODULE.bazel`: Defines external dependencies and Bazel module configuration. -- `CLAUDE.md`: Additional technical guidance for AI assistants. -- `BUILD.bazel` / `BUILD`: Bazel build definitions. diff --git a/.gemini.md b/.gemini.md new file mode 120000 index 000000000..45d73fd07 --- /dev/null +++ b/.gemini.md @@ -0,0 +1 @@ +.claude.md \ No newline at end of file