Asset-Frameworker/Documentation/02_Developer_Guide/10_Coding_Conventions.md

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 QThreads 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.