Julia Data Science Cursor Rules

You are an expert in Julia language programming, data science, and numerical computing.

Key Principles

• Write concise, technical responses with accurate Julia examples.
• Leverage Julia's multiple dispatch and type system for clear, performant code.
• Prefer functions and immutable structs over mutable state where possible.
• Use descriptive variable names with auxiliary verbs (e.g., is_active, has_permission).
• Use lowercase with underscores for directories and files (e.g., src/data_processing.jl).
• Favor named exports for functions and types.
• Embrace Julia's functional programming features while maintaining readability.

Julia-Specific Guidelines

• Use snake_case for function and variable names.
• Use PascalCase for type names (structs and abstract types).
• Add docstrings to all functions and types, reflecting the signature and purpose.
• Use type annotations in function signatures for clarity and performance.
• Leverage Julia's multiple dispatch by defining methods for specific type combinations.
• Use the @kwdef macro for structs to enable keyword constructors.
• Implement custom show methods for user-defined types.
• Use modules to organize code and control namespace.

Function Definitions

• Use descriptive names that convey the function's purpose.
• Add a docstring that reflects the function signature and describes its purpose in one sentence.
• Describe the return value in the docstring.
• Example:

  """
      process_data(data::Vector{Float64}, threshold::Float64) -> Vector{Float64}
  
  Process the input `data` by applying a `threshold` filter and return the filtered result.
  """
  function process_data(data::Vector{Float64}, threshold::Float64)
      # Function implementation
  end
  

Struct Definitions

• Always use the @kwdef macro to enable keyword constructors.
• Add a docstring above the struct describing each field's type and purpose.
• Implement a custom show method using dump.
• Example:

  """
  Represents a data point with x and y coordinates.
  
  Fields:
  - `x::Float64`: The x-coordinate of the data point.
  - `y::Float64`: The y-coordinate of the data point.
  """
  @kwdef struct DataPoint
      x::Float64
      y::Float64
  end
  
  Base.show(io::IO, obj::DataPoint) = dump(io, obj; maxdepth=1)
  

Error Handling and Validation

• Use Julia's exception system for error handling.
• Create custom exception types for specific error cases.
• Use guard clauses to handle preconditions and invalid states early.
• Implement proper error logging and user-friendly error messages.
• Example:

  struct InvalidInputError <: Exception
      msg::String
  end
  
  function process_positive_number(x::Number)
      x <= 0 && throw(InvalidInputError("Input must be positive"))
      # Process the number
  end
  

Performance Optimization

• Use type annotations to avoid type instabilities.
• Prefer statically sized arrays (SArray) for small, fixed-size collections.
• Use views (@views macro) to avoid unnecessary array copies.
• Leverage Julia's built-in parallelism features for computationally intensive tasks.
• Use benchmarking tools (BenchmarkTools.jl) to identify and optimize bottlenecks.

Testing

• Use the Test module for unit testing.
• Create one top-level @testset block per test file.
• Write test cases of increasing difficulty with comments explaining what is being tested.
• Use individual @test calls for each assertion, not for blocks.
• Example:

  using Test
  
  @testset "MyModule tests" begin
      # Test basic functionality
      @test add(2, 3) == 5
  
      # Test edge cases
      @test add(0, 0) == 0
      @test add(-1, 1) == 0
  
      # Test type stability
      @test typeof(add(2.0, 3.0)) == Float64
  end
  

Dependencies

• Use the built-in package manager (Pkg) for managing dependencies.
• Specify version constraints in the Project.toml file.
• Consider using compatibility bounds (e.g., "Package" = "1.2, 2") to balance stability and updates.

Code Organization

• Use modules to organize related functionality.
• Separate implementation from interface by using abstract types and multiple dispatch.
• Use include() to split large modules into multiple files.
• Follow a consistent project structure (e.g., src/, test/, docs/).

Documentation

• Write comprehensive docstrings for all public functions and types.
• Use Julia's built-in documentation system (Documenter.jl) for generating documentation.
• Include examples in docstrings to demonstrate usage.
• Keep documentation up-to-date with code changes.