Coding Guidelines
=================

These guidelines ensure consistency and quality across the plugin's development. We follow standard practices for IntelliJ Platform SDK, Kotlin, and Python.

IntelliJ Platform SDK Practices
-------------------------------
- **API Versioning**: Always use the most recent, non-deprecated APIs. Check for ``@Deprecated`` annotations and follow suggestions in their Javadoc.
- **Logging**: Use ``com.intellij.openapi.diagnostic.Logger`` for plugin logging instead of ``println`` or custom file logging for general diagnostic purposes.
- **Services**: Use the ``@Service`` annotation for project-level or application-level services. Avoid manual singleton patterns.
- **Process Execution**: Use ``com.intellij.execution.configurations.GeneralCommandLine`` for launching external processes.
- **File I/O**: Prefer ``java.nio.file.Path`` and IntelliJ's ``VfsUtil``, ``FileUtil``, or ``NioPathUtil`` over ``java.io.File`` when interacting with the IDE's virtual file system.
- **Network**: Use ``com.intellij.util.io.HttpRequests`` for downloading files or making network requests.
- **UI Components**: Use IntelliJ-specific components like ``JBLabel``, ``JBTextField``, ``JBCheckBox``, and ``FormBuilder`` for consistent UI.
- **Progress**: Long-running operations should be wrapped in ``ProgressManager.getInstance().runProcessWithProgressSynchronously`` or ``runModal`` to provide feedback.

Kotlin Styling Practices
------------------------
- **Standard Conventions**: Follow the official `Kotlin Style Guide <https://kotlinlang.org/docs/coding-conventions.html>`_.
- **Immutability**: Use ``val`` by default. Only use ``var`` when mutability is strictly required.
- **Single-Expression Functions**: Use expression bodies (``fun foo() = ...``) for simple functions.
- **Null Safety**: Leverage Kotlin's null safety effectively; avoid ``!!`` where possible, prefer ``?:`` (elvis operator) or safe calls.
- **Naming**:

  - ``PascalCase`` for classes, interfaces, and objects.
  - ``camelCase`` for functions, variables, and properties.
  - ``UPPER_SNAKE_CASE`` for constants.

- **String Templates**: Prefer string templates (``"$foo"``) over concatenation.

Python Styling Practices
------------------------
- **PEP 8**: Follow PEP 8 standards for any Python scripts (like those injected into Blender).
- **Nesting**: Keep nesting minimal (<= 4 levels of indentation).
- **Standard Library**: Prefer using the Python standard library whenever possible.

Clean & Readable Code Practices
-------------------------------
- **Single Responsibility Principle (SRP)**: Each class and function should have one clear purpose. Decompose large classes if they handle multiple distinct responsibilities.
- **Descriptive Naming**: Use names that clearly state the intent of the variable, function, or class. Avoid cryptic abbreviations.
- **Function Size**: Aim for small, focused functions. If a function is too long, extract sub-functions.
- **DRY (Don't Repeat Yourself)**: Extract common logic into helper methods or utility classes.
- **Constant Extraction**: Avoid hardcoded strings or numbers. Extract them into meaningful constants.
- **Comments**: Write code that is self-documenting. Use comments only to explain "why" something is done if it's not obvious from the "what" and "how".