# Developer Guide: Coding Conventions

This document outlines the coding conventions and general practices followed within the Asset Processor Tool codebase. Adhering to these conventions helps maintain consistency and readability.

## General Principles

*   **Readability:** Code should be easy to read and understand. Use clear variable and function names.
*   **Consistency:** Follow existing patterns and styles within the codebase.
*   **Maintainability:** Write code that is easy to modify and extend.
*   **Explicitness:** Be explicit rather than implicit.

## Specific Conventions

*   **Object-Oriented Programming (OOP):** The codebase heavily utilizes classes to structure the application logic (e.g., `AssetProcessor`, `Configuration`, `MainWindow`, various Handlers). Follow standard OOP principles.
*   **Type Hinting:** Use Python type hints throughout the code to indicate the expected types of function arguments, return values, and variables. This improves code clarity and allows for static analysis.
*   **Logging:** Use the standard Python `logging` module for all output messages (information, warnings, errors, debug). Avoid using `print()` for application output. Configure log levels appropriately. The GUI uses a custom `QtLogHandler` to integrate logging with the UI.
*   **Error Handling:** Use standard `try...except` blocks to handle potential errors gracefully. Define and use custom exceptions (e.g., `ConfigurationError`, `AssetProcessingError`) for specific error conditions within the application logic. Log exceptions with `exc_info=True` to include traceback information.
*   **Parallelism:** When implementing CPU-bound tasks that can be run concurrently, use `concurrent.futures.ProcessPoolExecutor` as demonstrated in `main.py` and `gui/processing_handler.py`. Ensure that shared state is handled correctly (e.g., by instantiating necessary objects within worker processes).
*   **GUI Development (`PySide6`):**
    *   Use Qt's signals and slots mechanism for communication between objects, especially across threads.
    *   Run long-running or blocking tasks in separate `QThread`s to keep the main UI thread responsive.
    *   Perform UI updates only from the main UI thread.
*   **Configuration:** Core settings are managed in `config.py` (Python module). Supplier-specific rules are managed in JSON files (`Presets/`). The `Configuration` class handles loading and merging these.
*   **File Paths:** Use `pathlib.Path` objects for handling file system paths. Avoid using string manipulation for path joining or parsing.
*   **Docstrings:** Write clear and concise docstrings for modules, classes, methods, and functions, explaining their purpose, arguments, and return values.
*   **Comments:** Use comments to explain complex logic or non-obvious parts of the code.
*   **Imports:** Organize imports at the top of the file, grouped by standard library, third-party libraries, and local modules.
*   **Naming:**
    *   Use `snake_case` for function and variable names.
    *   Use `PascalCase` for class names.
    *   Use `UPPER_CASE` for constants.
    *   Use a leading underscore (`_`) for internal or "protected" methods/attributes.

Adhering to these conventions will make the codebase more consistent, easier to understand, and more maintainable for all contributors.