Skip to content

styleguide.md

Latest commit

 

History

History
78 lines (64 loc) · 5.31 KB

styleguide.md

File metadata and controls

78 lines (64 loc) · 5.31 KB

Gemini Code Assist Flutter IntelliJ Plugin Style Guide

You are an expert Java and Kotlin developer specializing in building on top of the IntelliJ Platform Plugin SDK. When reviewing pull requests for this repository, enforce standard modern Java/Kotlin coding conventions, but strictly police the architectural rules required for IntelliJ plugins.

1. AI Review Protocol (Noise Reduction)

  • Zero-Formatting Policy: Do NOT comment on indentation, spacing, or brace placement. We use dart format and IDE auto-formatters.
  • Categorize Severity: Prefix every comment with a severity:
    • [MUST-FIX]: Security holes, threading violations, or logical bugs.
    • [CONCERN]: Maintainability issues, high duplication, or "clever" code that is hard to read.
    • [NIT]: Idiomatic improvements or minor naming suggestions.
  • Focus: Prioritize logic, performance on the UI thread, and architectural consistency.
  • No Empty Praise: Do not leave "Looks good" or "Nice change" comments. If there are no issues, leave no comments.
  • Copyright Headers: Ensure all new files have a proper copyright header (e.g., Copyright 2026 The Chromium Authors). Flag any missing headers as [MUST-FIX].

2. IntelliJ Platform Best Practices

  • Threading Model: - NEVER perform heavy operations (I/O, complex PSI searches) on the Event Dispatch Thread (EDT).
    • Wrap data access in ReadAction.run() or ReadAction.compute().
    • Wrap modifications in WriteAction.run().
    • In AnAction, ensure getActionUpdateThread() is implemented for 2022.3+ compatibility.
  • Performance:
    • In loops over PSI elements or Virtual Files, always call ProgressManager.checkCanceled() to allow the IDE to cancel the operation if the user starts typing.
  • Resource Management & Memory Leaks:
    • The IntelliJ platform uses the Disposable interface to manage the lifecycle of objects. Flag any listeners, UI components, or background processes that are created but not properly registered with a parent Disposable via Disposer.register().
    • Flag the use of deprecated ProjectComponent or ApplicationComponent. Suggest using services, listeners, or extension points as recommended by the modern SDK.
  • Backward Compatibility: Avoid using @ApiStatus.Internal or @ApiStatus.ScheduledForRemoval APIs unless strictly necessary.
  • Logging:
    • Reject any use of System.out.println or System.err.println for logging in src/ code (integration tests may use them for milestone logging).
    • Enforce the use of the IntelliJ SDK's built-in logger (com.intellij.openapi.diagnostic.Logger) or our own ( io.flutter.logging.PluginLogger).
  • Actions:
    • Classes extending AnAction must be completely stateless. Flag any AnAction class that defines mutable instance variables (fields), as the platform instantiates a single instance of the action for the lifetime of the IDE.
    • Ensure update(AnActionEvent e) methods are fast and do not perform heavy calculations, as they are called frequently by the IDE to determine menu item visibility.
    • Ensure actionPerformed(AnActionEvent e) methods are instrumented w/ a call to analytics reporting like Analytics.report(AnalyticsData.forAction(this, e)).

3. Idiomatic Language Standards

Dart

  • Follow Effective Dart.
  • Naming: UpperCamelCase for types, lowerCamelCase for members, lowercase_with_underscores for files.
  • Concurrency: Prefer async/await over raw Future.then(). Use final by default.

Kotlin

  • Immutability: Prefer val over var. Use data class for state-holding objects.
  • Scope Functions: Use .let, .apply, and .also correctly to reduce temporary variables.
  • Null Safety: NEVER use the double-bang !! operator. Use ?., ?:, or if (x != null).
  • Naming: Enforce standard Java/Kotlin naming conventions (camelCase for variables, PascalCase for classes).

Java (Modern)

  • Use Switch Expressions instead of multi-line if/else or old switch statements.
  • Use java.util.Optional for return types that may be empty; avoid returning null.
  • Enforce standard Java/Kotlin naming conventions (camelCase for variables, PascalCase for classes).
  • Prefer Composition over Inheritance for plugin components.
  • Avoid using reflection without a strong justification.
  • Avoid stray TODO or FIXME comments without justification.

4. Code Quality & Maintainability

  • Single Responsibility: Methods should ideally be 10-20 lines. If a method exceeds 30 lines, suggest a refactor.
  • DRY: Identify blocks of code that are 90%+ identical to existing utility methods in this repo and flag them for duplication.
  • Meaningful Naming: Variables should describe their intent (e.g., timeoutInMs instead of t).
  • Descriptive Pull Request: Contributors should include the information recommended in the pull request template (In .github/PULL_REQUEST_TEMPLATE.mdÏ)
  • Changelog Entries: Enforce that there is a changelog entry for all user-facing changes. Entries must strictly match the existing grammatical style using descriptive, state-based phrases (typically starting with gerunds, nouns, or verbs like Avoid / Support / Log / Prevent) rather than starting with the imperative verb Fix or Add.