Skip to content

Terminology Conventions - Grid Building Plugin

Core Terminology Standards

Validation and Error Handling

"Issues" vs "Problems"

  • ✅ CORRECT: Use "issues" for validation failures, error conditions, and problems encountered during operations
  • ❌ INCORRECT: Do not use "problems" - this creates inconsistent terminology across the codebase

Examples:

# ✅ CORRECT: Consistent "issues" terminology
var validation_issues := validator.get_validation_issues()
var setup_issues := rule.setup(params)
var dependency_issues := validate_dependencies()

# ❌ INCORRECT: Mixed terminology
var validation_problems := validator.get_validation_problems()
var setup_issues := rule.setup(params)  # Inconsistent with above

Rationale:

  • "Issues" is more neutral and professional
  • Consistent terminology improves code readability and searchability
  • Aligns with standard software development practices

Variable and Method Naming

  • Dictionary/Array Names: issues_dictionary, validation_issues, setup_issues
  • Method Names: get_validation_issues(), validate_dependencies(), check_setup_issues()
  • Documentation: Always refer to validation failures as "issues" in comments and docstrings

Method Naming Conventions

Setup and Validation Methods

  • setup() - Configure system/component state and return issues found
  • validate() - Check current state and return validation results
  • validate_dependencies() - Verify required dependencies are present
  • get_validation_issues() - Retrieve current validation issues without re-checking

Cleanup Methods

  • tear_down() - Final cleanup before freeing or permanent destruction
  • reset() - Clear/reinitialize state for reuse (less common, use tear_down() unless reuse is explicit)

Implementation Guidelines

Code Review Checklist

When reviewing code or making changes, ensure:

  • [ ] All validation failure references use "issues" not "problems"
  • [ ] Variable names consistently use "issues" suffix/prefix
  • [ ] Method names align with established conventions
  • [ ] Documentation and comments use standardized terminology
  • [ ] Error messages and user feedback use "issues" terminology

Refactoring Rules

  1. Immediate Fix: When encountering "problems" terminology, update to "issues" immediately
  2. Comprehensive Search: Use grep_search to find all instances of mixed terminology
  3. Documentation Update: Update related documentation to reflect terminology changes
  4. Consistent Naming: Ensure variable names, method names, and comments all align

AI Assistant Instructions

Automatic Correction Policy:

  • When AI assistants encounter inconsistent terminology (using "problems" instead of "issues"), they should automatically correct it
  • Update all related variable names, method references, and documentation in the same operation
  • Document the correction in code comments when significant refactoring is involved

Search Patterns for Detection:

# Find mixed terminology usage
grep -r "problem" --include="*.gd" addons/grid_building/
grep -r "Problem" --include="*.gd" addons/grid_building/

# Exclude legitimate uses (like "problem_matcher" in tasks.json)
grep -r "problem" --include="*.gd" --exclude="*problem_matcher*" addons/grid_building/

Logging and Output Volume Guidelines

  • When verbose logging floods the output (e.g., stack overflow or editor output overflow), reduce message count:
  • Lower debug level from VERBOSE to INFO in GBDebugSettings or logger settings
  • Aggregate repeated lines into a single summary (e.g., count duplicates instead of printing each)
  • Log per-rule summaries instead of per-indicator details, unless actively debugging that area
  • Prefer concise, actionable messages. Only enable per-indicator logging temporarily during active investigation.

Historical Context

Recent Updates (August 7, 2025)

  • PlacementValidator.gd: Updated problem_dictionary → issues_dictionary, rule_problems → rule_issues
  • Method Documentation: Updated docstring comments to use "issues" consistently
  • Signal Parameters: setup_failed signal now emits issues parameter instead of problems

Common Locations for Mixed Terminology

  • Validation methods in component classes
  • Setup and configuration methods
  • Error handling and logging code
  • Test assertion messages
  • User-facing error messages

Related Documents:

Enforcement: This convention should be automatically enforced by AI assistants and during code reviews. When in doubt, always choose "issues" over any alternative terminology for consistency.