# WPF Code Guidelines

* Use modern C# and current .NET/WPF conventions.
* Keep UI, application logic and domain logic clearly separated.
* Prefer MVVM for non-trivial views.
* Keep code-behind minimal.
* Use code-behind only for view-specific behavior that does not belong in the ViewModel.
* Avoid business logic in views.
* Avoid direct service access from controls.
* Keep dependencies explicit and testable.
* Prefer composition over inheritance.
* Avoid unnecessary abstractions and framework wrappers.
* Follow the existing project architecture unless there is a strong reason to change it.

## MVVM

* Keep ViewModels focused on presentation state and commands.
* Do not put UI element references into ViewModels.
* Do not access `Window`, `UserControl`, `DispatcherObject` or visual tree elements from ViewModels.
* Avoid direct navigation, dialogs or message boxes from ViewModels without an abstraction when testability matters.
* Prefer explicit application services for navigation, dialogs and external interactions.
* Keep domain logic outside ViewModels.
* Do not use ViewModels as general-purpose service containers.
* Keep ViewModel dependencies minimal.
* Prefer immutable or readonly state where practical.
* Avoid duplicated derived state.
* Keep state transitions predictable.

## Data Binding

* Prefer data binding over manual UI synchronization.
* Use strongly typed properties.
* Use appropriate binding modes.
* Prefer `OneWay` when two-way updates are not required.
* Use `TwoWay` only when the UI must modify the source.
* Avoid unnecessary `UpdateSourceTrigger=PropertyChanged` for expensive operations.
* Keep binding paths simple and stable.
* Avoid deeply nested binding paths.
* Do not hide broken bindings.
* Treat binding errors as real defects.
* Use `FallbackValue` and `TargetNullValue` only when they reflect intended behavior.
* Avoid excessive converters.
* Prefer exposing correctly shaped state from the ViewModel over complex converter logic.
* Avoid `MultiBinding` when simpler state modeling is clearer.
* Do not put business logic into converters.

## Property Change Notifications

* Implement property change notifications consistently.
* Avoid raising `PropertyChanged` unnecessarily.
* Raise notifications only when values actually change.
* Keep dependent property notifications explicit.
* Avoid hidden notification chains that are difficult to reason about.
* Prefer reusable base implementations only when they reduce duplication without obscuring behavior.
* Do not use reflection-based notification mechanisms unless there is a concrete benefit.

## Commands

* Prefer commands over click handlers for ViewModel-driven actions.
* Keep command execution focused.
* Avoid putting large workflows directly inside command implementations.
* Keep `CanExecute` logic cheap.
* Refresh command availability only when relevant state changes.
* Avoid command implementations with hidden side effects.
* Handle async commands safely.
* Prevent accidental duplicate execution when an async action must not run concurrently.
* Never use `async void` except for true event handlers.

## Async and Threading

* Keep async operations asynchronous throughout the call chain.
* Avoid `.Result`, `.Wait()` and other synchronous blocking of async work.
* Do not block the UI thread.
* Run I/O asynchronously.
* Move expensive CPU work off the UI thread only when necessary.
* Marshal UI updates back to the UI thread when required.
* Keep Dispatcher usage minimal and explicit.
* Do not use the Dispatcher to hide incorrect threading design.
* Support `CancellationToken` for cancellable long-running operations.
* Cancel obsolete work when views or selections change.
* Prevent race conditions caused by overlapping async operations.
* Handle exceptions from background operations explicitly.

## UI Thread

* Treat the UI thread as a scarce resource.
* Avoid expensive loops, parsing, serialization, database access or network calls on the UI thread.
* Avoid excessive Dispatcher invocations.
* Batch UI updates where practical.
* Do not update UI-bound collections excessively in tight loops.
* Avoid synchronous waits on background work.
* Keep rendering-related callbacks lightweight.

## Collections

* Use `ObservableCollection<T>` only when collection change notifications are required.
* Do not use `ObservableCollection<T>` as a general-purpose collection.
* Use `List<T>` or other suitable collections for non-observable internal data.
* Avoid replacing entire observable collections when incremental updates are sufficient.
* Avoid thousands of individual collection notifications when a bulk update is more appropriate.
* Keep collection mutations on the correct thread.
* Avoid exposing mutable internal collections unnecessarily.
* Prefer read-only views where consumers should not modify data.

## XAML

* Keep XAML readable and focused.
* Avoid excessively large view files.
* Split complex views into focused controls when it improves maintainability.
* Use resources for repeated values and styles.
* Avoid magic numbers in XAML.
* Keep styles and templates consistent.
* Avoid excessive inline styling.
* Prefer reusable resources over duplicated markup.
* Avoid deeply nested panels.
* Keep visual trees as shallow as practical.
* Use semantic control choices.
* Avoid unnecessary containers.
* Do not overuse triggers when simpler state representation is possible.
* Keep templates understandable.
* Avoid XAML tricks that make behavior hard to discover.

## Layout

* Prefer `Grid` for structured layouts.
* Use `StackPanel` only where its layout behavior is actually appropriate.
* Avoid unnecessary nested panels.
* Avoid fixed sizes unless the design requires them.
* Prefer responsive sizing with `Auto` and `*`.
* Avoid layout configurations that cause excessive measure/arrange passes.
* Be careful with large visual trees inside scrolling containers.
* Avoid disabling virtualization accidentally.

## Virtualization

* Keep UI virtualization enabled for large collections.
* Do not use container layouts that disable virtualization without a reason.
* Avoid wrapping large virtualized item lists in additional scrolling containers.
* Use virtualizing panels where appropriate.
* Verify virtualization when displaying large data sets.
* Avoid rendering thousands of controls simultaneously.
* Prefer paging, incremental loading or virtualization for very large data sets.

## Resources and Styles

* Use shared resources for repeated styles, brushes, templates and dimensions.
* Keep resource dictionaries focused.
* Avoid giant global resource dictionaries.
* Prefer feature-level resources when styles are not truly global.
* Use `StaticResource` by default.
* Use `DynamicResource` only when runtime resource replacement is required.
* Avoid excessive dynamic resource lookups.
* Keep theme resources separated from application logic.
* Avoid hardcoded colors and dimensions when design tokens or resources already exist.

## Dependency Properties

* Use dependency properties only when WPF property-system behavior is required.
* Do not use dependency properties as a replacement for normal CLR properties.
* Keep metadata and callbacks lightweight.
* Avoid expensive work in property-changed callbacks.
* Avoid callbacks with hidden side effects.
* Validate or coerce values only when the control contract requires it.
* Do not expose mutable default values in dependency property metadata.

## Attached Properties and Behaviors

* Use attached properties and behaviors for reusable view-specific behavior.
* Do not use them to hide business logic.
* Keep behaviors focused and predictable.
* Clean up event handlers when behaviors are detached.
* Avoid global attached-property state.
* Prefer explicit behavior over complex XAML hacks.

## Events

* Avoid unnecessary event subscriptions.
* Unsubscribe from long-lived publishers when required.
* Prevent memory leaks from event handlers.
* Prefer weak events where publisher lifetime significantly exceeds subscriber lifetime.
* Keep event handlers small.
* Do not use events as hidden global communication channels.
* Avoid excessive event chaining.

## Memory Management

* Watch for memory leaks caused by:

  * Event subscriptions
  * Timers
  * Static references
  * Long-lived services
  * Cached views
  * Closures
  * Collection views
  * Binding-related references
* Dispose resources correctly.
* Stop timers and background work when no longer needed.
* Avoid retaining closed windows or unloaded views.
* Do not keep unnecessary references to visual elements.
* Profile memory when long-running applications continuously grow.

## Windows and Dialogs

* Keep window lifecycle explicit.
* Avoid creating duplicate windows unintentionally.
* Do not keep hidden windows alive without a reason.
* Separate dialog logic from business logic.
* Prefer dialog services when ViewModels need to request user interaction.
* Keep ownership relationships explicit.
* Avoid application shutdown behavior that depends on accidental window lifetime.

## Navigation

* Keep navigation state explicit.
* Avoid coupling ViewModels directly to concrete views.
* Avoid service locator patterns for view resolution.
* Keep navigation history intentional.
* Dispose or release navigation targets when they are no longer required.
* Do not retain entire navigation graphs unnecessarily.

## Validation

* Validate user input at the appropriate boundary.
* Keep validation logic out of XAML when it becomes complex.
* Prefer reusable validation rules or ViewModel validation for non-trivial cases.
* Display validation errors consistently.
* Do not rely on UI validation as a security boundary.
* Validate again at backend or domain boundaries when required.
* Preserve user input on recoverable errors.

## Performance

* Keep the UI thread responsive.
* Minimize visual tree depth.
* Keep virtualization enabled.
* Avoid unnecessary bindings.
* Avoid unnecessary converters.
* Avoid unnecessary resource lookups.
* Avoid unnecessary property change notifications.
* Avoid frequent full collection refreshes.
* Avoid loading large datasets eagerly.
* Avoid loading large images at full resolution when unnecessary.
* Freeze `Freezable` objects where practical.
* Reuse immutable resources where appropriate.
* Avoid unnecessary animations.
* Avoid high-frequency timers on the UI thread.
* Measure startup time, UI responsiveness, memory usage and rendering performance before micro-optimizing.

## Images and Media

* Load images at an appropriate resolution.
* Avoid decoding images significantly larger than their displayed size.
* Release streams and file handles correctly.
* Avoid locking image files unintentionally.
* Cache images only when there is a clear memory strategy.
* Avoid keeping large bitmaps alive unnecessarily.
* Prefer frozen image resources when they are immutable.

## Security

* Treat all external input as untrusted.
* Never expose secrets, credentials or tokens in UI code.
* Do not store secrets in configuration files committed to source control.
* Avoid leaking sensitive information through logs, dialogs or exception messages.
* Validate file paths and external resources.
* Do not execute external processes or files without explicit validation.
* Avoid insecure deserialization.
* Do not weaken TLS, authentication or certificate validation.
* Prefer secure defaults.
* Never disable security controls for convenience.

## File and Process Access

* Validate file paths before use.
* Avoid assuming files or directories exist.
* Handle permissions and locked files gracefully.
* Avoid arbitrary shell execution.
* Quote and validate process arguments safely.
* Do not concatenate untrusted input into shell commands.
* Avoid elevated privileges unless explicitly required.
* Clean up temporary files when appropriate.

## Error Handling

* Handle expected errors explicitly.
* Do not swallow exceptions.
* Preserve useful exception context.
* Avoid showing raw technical exceptions directly to end users.
* Log enough information for diagnosis without exposing sensitive data.
* Keep user-facing error messages clear and actionable.
* Avoid using exceptions for normal control flow.
* Ensure background exceptions are observed.

## Logging

* Use structured logging.
* Avoid excessive logging on the UI thread.
* Do not log every property change or binding update.
* Never log secrets, tokens, credentials or sensitive user data.
* Include relevant context for operational failures.
* Avoid logging the same exception repeatedly at multiple layers.

## Architecture

* Keep presentation, application, domain and infrastructure concerns separated.
* Avoid direct database access from views or ViewModels.
* Avoid direct HTTP access from controls.
* Keep external integrations behind focused services.
* Avoid circular dependencies.
* Keep feature boundaries clear.
* Do not create shared utility classes for unrelated functionality.
* Keep shared code genuinely reusable.
* Minimize global state.
* Avoid static service access.

## Dependency Injection

* Use dependency injection where lifecycle management, substitution or testability benefits from it.
* Avoid service locator patterns.
* Keep constructor dependencies minimal.
* Do not inject dependencies that are not used.
* Choose service lifetimes intentionally.
* Do not make stateful services global without a concrete reason.
* Avoid introducing interfaces solely for dependency injection when no abstraction is needed.

## Testing

* Keep ViewModels testable without a UI thread where practical.
* Test behavior rather than implementation details.
* Test domain and application logic independently from WPF.
* Avoid brittle tests coupled to XAML structure.
* Keep UI automation tests focused on critical flows.
* Mock external boundaries rather than internal details.
* Keep tests deterministic.
* Avoid real network, database or filesystem dependencies in unit tests unless explicitly intended.

## Code Quality

* Use nullable reference types.
* Prefer modern, readable C# syntax.
* Avoid unnecessary interfaces and abstractions.
* Prefer concrete types where no abstraction is required.
* Use descriptive names.
* Remove dead code.
* Remove commented-out code.
* Do not add comments unless the user explicitly requests them.
* Treat compiler, analyzer and binding warnings seriously.
* Do not suppress warnings without a concrete reason.
* Prefer correctness, responsiveness, security and maintainability over cleverness.

## Performance Priority

Prioritize WPF performance work in this order:

* UI architecture
* UI thread blocking
* Data loading and I/O
* Virtualization
* Visual tree complexity
* Binding and notification frequency
* Rendering and images
* Memory retention and leaks
* Allocations
* CPU micro-optimizations

Never optimize based purely on assumptions.

## Safety Rule

* The UI must remain responsive.
* Do not block the UI thread with I/O or expensive CPU work.
* Do not bypass validation or security controls for convenience.
* Do not introduce hidden cross-thread access.
* Prefer predictable, explicit and testable UI behavior.