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.

  • 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”.