Cline

# Deployment and DevOps Standards for F# This document outlines coding standards and best practices for deployment and DevOps specific to F#. It aims to guide developers in building, deploying, and operating F# applications efficiently and reliably, while leveraging the advantages of the F# language and ecosystem. ## 1. Build Processes and CI/CD ### 1.1. Standard: Use .NET SDK-based Builds **Do This:** Use the .NET SDK's build system directly or through a build automation tool. **Don't Do This:** Rely on custom or outdated build scripts. **Why:** The .NET SDK offers a consistent and well-supported build process. Utilizing it ensures compatibility, simplifies dependencies, and provides built-in support for features like NuGet package management. **Example:** """fsharp // build.fsx (FAKE build script) #r "paket: groupref FAKE remoting" open Fake.Core open Fake.DotNet open Fake.IO open Fake.IO.FileSystem open Fake.Paket Target.create "Restore" (fun _ -> Paket.Restore () ) Target.create "Build" (fun _ -> DotNet.build (fun p -> { p with Configuration = BuildConfiguration.Release Framework = DotNet.NET.TargetFramework.net60 } ) "src/YourProject.fsproj" ) Target.create "Test" (fun _ -> DotNet.test (fun p -> { p with Configuration = BuildConfiguration.Release } ) "tests/YourProject.Tests.fsproj" ) Target.create "Publish" (fun _ -> DotNet.publish (fun p -> { p with Configuration = BuildConfiguration.Release Framework = DotNet.NET.TargetFramework.net60 Output = "output" } ) "src/YourProject.fsproj" ) Target.create "Default" (fun _ -> Fake.Core.BuildServer.Build [ "Restore" "Build" "Test" "Publish" ] ) RunTargetOrDefault "Default" """ **Anti-Pattern:** Using ad-hoc shell scripts for building, leading to inconsistencies between environments. ### 1.2. Standard: Implement Comprehensive CI/CD Pipelines **Do This:** Use a CI/CD platform (e.g., Azure DevOps, GitHub Actions, GitLab CI) with automated builds, tests, and deployments. **Don't Do This:** Manual builds and deployments. **Why:** Automating the build and deployment process streamlines development, reduces errors, and enables faster and more frequent releases. **Example (GitHub Actions):** """yaml # .github/workflows/dotnet.yml name: .NET Build and Test on: push: branches: [ main ] pull_request: branches: [ main ] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Setup .NET uses: actions/setup-dotnet@v3 with: dotnet-version: 6.0 - name: Restore dependencies run: dotnet restore - name: Build run: dotnet build --configuration Release - name: Test run: dotnet test --configuration Release --no-restore --verbosity normal - name: Publish run: dotnet publish src/YourProject.fsproj -c Release -o out - name: Upload artifact uses: actions/upload-artifact@v3 with: name: package path: out """ **Anti-Pattern:** Infrequent integrations and manual deployment processes lead to "integration hell" and slow release cycles. ### 1.3: Standard: Embrace Immutable Infrastructure **Do This:** Deploy applications as immutable artifacts (e.g., Docker images, Azure ARM templates). **Don't Do This:** Modifying servers in-place. **Why:** Immutable infrastructure ensures consistency between environments, reduces configuration drift, and simplifies rollbacks. **Example (Dockerfile):** """dockerfile FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS base WORKDIR /app EXPOSE 80 EXPOSE 443 FROM mcr.microsoft.com/dotnet/sdk:6.0 AS build WORKDIR /src COPY ["src/YourProject/YourProject.fsproj", "src/YourProject/"] RUN dotnet restore "src/YourProject/YourProject.fsproj" COPY . . WORKDIR "/src/src/YourProject" RUN dotnet build "YourProject.fsproj" -c Release -o /app/build FROM build AS publish RUN dotnet publish "YourProject.fsproj" -c Release -o /app/publish FROM base AS final WORKDIR /app COPY --from=publish /app/publish . ENTRYPOINT ["dotnet", "YourProject.dll"] """ **Why This Matters for F#**: Immutable infrastructure is particularly useful with F# because compiling F# code produces self-contained applications that are easy to package into Docker containers. This simplifies deployment and ensures consistency across environments. ### 1.4. Standard: Implement Infrastructure as Code (IaC) **Do This:** Define your infrastructure declaratively using tools like Azure Resource Manager (ARM) templates, Terraform, or Pulumi directly within your solutions. **Don't Do This:** Manually provisioning or configuring infrastructure. **Why:** IaC provides version control for infrastructure, simplifies provisioning, ensures repeatability, facilitates disaster recovery, and enables self-service deployment. **Example (Terraform):** """terraform resource "azurerm_resource_group" "example" { name = "example-resources" location = "West Europe" } resource "azurerm_app_service_plan" "example" { name = "example-appserviceplan" location = azurerm_resource_group.example.location resource_group_name = azurerm_resource_group.example.name sku { tier = "Standard" size = "S1" } } resource "azurerm_app_service" "example" { name = "example-appservice" location = azurerm_resource_group.example.location resource_group_name = azurerm_resource_group.example.name app_service_plan_id = azurerm_app_service_plan.example.id site_config { dotnet_framework_version = "v6.0" } app_settings = { "APPINSIGHTS_INSTRUMENTATIONKEY" = "<your_app_insights_key>" } } """ **Anti-Pattern:** Manually creating resources in the cloud console. ## 2. Production Considerations ### 2.1. Standard: Implement Centralized Logging **Do This:** Use a centralized logging system (e.g., Azure Monitor, ELK stack, Seq) to collect and analyze logs from all application instances. Structure your logs for easy analysis (e.g., use JSON). **Don't Do This:** Rely on local log files or console output. **Why:** Centralized logging provides visibility into application behavior, simplifies troubleshooting, and enables proactive monitoring. **Example (Logging with Serilog and structured data):** """fsharp open Serilog open Serilog.Events // Configure Serilog let logger = LoggerConfiguration() .MinimumLevel.Information() .WriteTo.Console() .WriteTo.Seq("http://localhost:5341") // Replace with your Seq instance .CreateLogger() // Use the logger let ProcessOrder orderId amount = try logger.Information("Processing order {OrderId} for amount {Amount}", orderId, amount) // Simulate processing if amount > 1000 then raise (System.Exception("Order amount exceeds limit")) logger.Information("Order {OrderId} processed successfully", orderId) true // Success with | ex -> logger.Error(ex, "Failed to process order {OrderId}", orderId) false // Failure // Example usage let orderResult = ProcessOrder 123 500 let orderResult2 = ProcessOrder 456 1500 //This will cause an error logged. """ **Anti-Pattern:** Scattered log files making it difficult to correlate events and diagnose issues. ### 2.2. Standard: Implement Health Checks **Do This:** Expose health check endpoints (e.g., "/healthz") that report the application's status. Integrate these endpoints with load balancers and monitoring systems. Consider using a dedicated health check library. **Don't Do This:** Lack of health checks. **Why:** Health checks allow automated systems to detect and respond to application failures, ensuring high availability. **Example (Health check in ASP.NET Core with F#):** """fsharp // Program.fs open Microsoft.AspNetCore.Builder open Microsoft.Extensions.DependencyInjection open Microsoft.AspNetCore.Hosting open Microsoft.Extensions.Hosting [<EntryPoint>] let main args = let builder = WebApplication.CreateBuilder(args) // Add services to the container. builder.Services.AddHealthChecks() |> ignore // Add health checks let app = builder.Build() // Configure the HTTP request pipeline. if app.Environment.IsDevelopment() then app.UseDeveloperExceptionPage() |> ignore app.UseRouting() |> ignore // Configure health check endpoint app.MapHealthChecks("/healthz") |> ignore app.Run() 0 """ **Anti-Pattern:** Ignoring health checks as part of deployment making it impossible to properly monitor and recover from system failures. ### 2.3. Standard: Implement Robust Error Handling and Circuit Breakers **Do This:** Use F#'s powerful pattern matching and "Result" type to handle errors gracefully. Wrap external service calls with circuit breakers to prevent cascading failures. **Don't Do This:** Ignoring exceptions or relying solely on try/catch blocks without providing specific handling. **Why:** Ensures resilience by preventing faults from propagating through the system. F#'s features are particularly well-suited for handling error conditions explicitly. **Example (Error Handling with "Result" and a simple Circuit Breaker):** """fsharp open System open System.Threading.Tasks type Result<'T, 'Error> = | Ok of 'T | Error of 'Error let tryGetValue (key: string) : Task<Result<string, string>> = task { try // Simulate fetching a value (e.g., from a database) if key = "validKey" then do! Task.Delay(100) // Simulate delay return Ok "TheValue" else do! Task.Delay(100) return Error $"Key '{key}' not found." with | ex -> return Error ex.Message } type CircuitBreakerState = | Closed | Open | HalfOpen type CircuitBreaker(failureThreshold: int, resetTimeout: TimeSpan) = let mutable currentState = Closed let mutable failureCount = 0 let mutable lastFailureTime = DateTime.MinValue let stateLock = obj() member this.ExecuteAsync<'T> (operation: unit -> Task<'T>) : Task<'T> = task { lock stateLock (fun () -> match currentState with | Closed -> try let! result = operation() failureCount <- 0 // Reset counter on success return result with | ex -> failureCount <- failureCount + 1 lastFailureTime <- DateTime.UtcNow if failureCount >= failureThreshold then currentState <- Open printfn "Circuit Breaker Opened" raise ex // Re-throw the exception | Open -> if DateTime.UtcNow - lastFailureTime > resetTimeout then currentState <- HalfOpen printfn "Circuit Breaker Half-Opened" try let! result = operation() failureCount <- 0 currentState <- Closed printfn "Circuit Breaker Closed" return result with | ex -> lastFailureTime <- DateTime.UtcNow printfn "Circuit Breaker Remains Open" raise ex else printfn "Circuit Breaker is Open - returning cached result or throwing exception" raise (Exception("Circuit Breaker Open")) // replace this! | HalfOpen -> try let! result = operation() failureCount <- 0 currentState <- Closed printfn "Circuit Breaker Closed" return result with | ex -> lastFailureTime <- DateTime.UtcNow currentState <- Open printfn "Circuit Breaker Re-Opened" raise ex ) |> ignore failwith "Unreachable Code" //Force Compiler to verify "return" statements } // Usage let circuitBreaker = CircuitBreaker(3, TimeSpan.FromSeconds(5.0)) let wrappedGetValue (key: string) : Task<Result<string, string>> = circuitBreaker.ExecuteAsync(fun () -> tryGetValue key) [<EntryPoint>] let main argv = task { let! result1 = wrappedGetValue "validKey" match result1 with | Ok value -> printfn "Value: %s" value | Error error -> printfn "Error: %s" error //Simulate multiple failures for i in 1..5 do try let! result = wrappedGetValue $"invalidKey_{i}" match result with | Ok value -> printfn "Value: %s" value | Error error -> printfn "Error: %s" error with | ex -> printfn $"Exception: {ex.Message}" do! Task.Delay(TimeSpan.FromSeconds(6.0)) let! result6 = wrappedGetValue "validKey" match result6 with | Ok value -> printfn "Value (after timeout): %s" value | Error error -> printfn "Error: %s" error } |> Async.AwaitTask |> ignore 0 """ **Anti-Pattern:** Uncaught exceptions bringing down the entire application. Services becoming unavailable due to overloaded dependent services. ### 2.4. Standard: Implement Application Insights and Monitoring **Do This:** Instrument your F# applications with Application Insights (or similar APM tools) to collect performance metrics, track dependencies, and monitor exceptions. Create custom metrics specific to your application domain. **Don't Do This:** Lack of performance monitoring and relying on anecdotal evidence to diagnose performance bottlenecks. **Why:** Provides actionable insights into application performance, helps identify bottlenecks, and allows for proactive optimization. **Example (Sending telemetry with Application Insights

# Code Style and Conventions Standards for F# This document outlines the F# code style and conventions standards designed to promote consistency, readability, and maintainability across all F# projects. Adhering to these standards will ensure that code is easily understood, modified, and collaborated on, especially when leveraging AI-powered coding assistants. ## 1. General Principles * **Succinctness:** F# embraces conciseness, but not at the expense of clarity. Aim for code that is easy to read and understand, even if it requires a few more lines. * **Expressiveness:** Leverage F#'s rich type system, pattern matching, and functional constructs to clearly express the intended logic. * **Composability:** Design functions and modules to be easily composed and reused. This promotes modularity and reduces code duplication. * **Immutability:** Prefer immutable data structures and functions with no side effects whenever possible. This simplifies reasoning about code and avoids many common bugs. ## 2. Formatting ### 2.1. Indentation * **Do This:** Use 4 spaces for indentation. Avoid tabs. * **Why:** Consistent indentation is crucial for readability. Spaces are preferred over tabs to avoid rendering issues across different editors and platforms. * **Example:** """fsharp let calculateArea width height = let area = width * height area """ * **Don't Do This:** Inconsistent indentation, mixing tabs and spaces. ### 2.2. Line Length * **Do This:** Aim for a maximum line length of 120 characters. * **Why:** Lines that are too long are difficult to read and can cause horizontal scrolling. * **How:** Break long lines after operators, commas, or other appropriate points. Indent the continuation lines to align with the start of the expression or statement. * **Example:** """fsharp let result = data |> List.map (fun x -> x * 2) |> List.filter (fun x -> x > 10) |> List.sum """ * **Don't Do This:** Exceeding line length, making code difficult to read. ### 2.3. Whitespace * **Do This:** * Use a single space after commas and colons. * Use a space around operators (e.g., "+", "-", "*", "/", "=", "<>", "::", "@"). * Use a single empty line between top-level definitions (functions, modules, types). * Use empty lines within functions to separate logical blocks of code. * **Why:** Whitespace enhances readability by visually separating different code elements. * **Example:** """fsharp let add x y = x + y let numbers = [ 1; 2; 3; 4; 5 ] let squaredNumbers = List.map (fun x -> x * x) numbers let total = List.sum squaredNumbers """ * **Don't Do This:** Inconsistent whitespace, which reduces readability. ### 2.4. Parentheses * **Do This:** * Use parentheses sparingly to clarify precedence. * Use parentheses for tuple arguments (e.g., "let add (x, y) = x + y"). * Avoid gratuitous parentheses. F# has well-defined precedence rules. Only use them when necessary to override or clarify. * **Why:** Excessive use of parentheses can clutter code and make it harder to read. * **Example:** """fsharp // Correct let result = 2 * (3 + 4) // Parentheses clarify precedence let add (x, y) = x + y // Parentheses for tuple argument // Incorrect let result = (2 * (3 + 4)) // Unnecessary parentheses """ * **Don't Do This:** Overusing or omitting parentheses where they are needed for precedence. ### 2.5. File Structure * **Do This:** * Organize code into modules within files. * Use a separate file for each module or closely related set of modules. * Match the file name to the module name (e.g., "MyModule.fs" for module "MyModule"). * Use "namespace" declarations for organizing types and modules hierarchically. * **Why:** Promotes modularity, maintainability, and code discoverability. * **Example:** """fsharp // File: MyNamespace.MyModule.fs namespace MyNamespace module MyModule = let myValue = 123 let myFunction x = x * 2 """ * **Don't Do This:** Large files with many unrelated modules, or inconsistent naming. ## 3. Naming Conventions ### 3.1. General Naming * **Do This:** Use descriptive and meaningful names that clearly indicate the purpose of the entity. * **Why:** Good names greatly improve code readability and reduce the need for comments. * **Example:** "calculateAverage" instead of "calcAvg", "userProfile" instead of "up". * **Don't Do This:** Using cryptic or abbreviated names that are difficult to understand. ### 3.2. Identifiers * **Do This:** * **Modules and Namespaces:** PascalCase (e.g., "MyModule", "MyNamespace"). * **Types:** PascalCase (e.g., "Customer", "Order"). * **Functions and Values:** camelCase (e.g., "calculateArea", "userName"). * **Parameters:** camelCase (e.g., "width", "height"). * **Record Fields:** camelCase (e.g., "firstName", "lastName"). * **Union Case Fields:** Apply the same rules as record fields. * **Type Parameters:** Single uppercase letter (e.g., "'T", "'U"). Use longer names for domain concepts (e.g. "'Order, 'Customer"). * **Interfaces:** "I" prefix followed by PascalCase (e.g., "ICustomerService"). * **Constants:** PascalCase with all-caps (e.g., "Pi", "MaxRetries") but prefer using immutable values. * **Why:** Consistent casing conventions improve code readability and help distinguish different kinds of symbols. * **Example:** """fsharp module UserManagement = type User = { FirstName : string LastName : string } let createUser firstName lastName = { FirstName = firstName; LastName = lastName } """ * **Don't Do This:** Inconsistent casing, using different conventions for similar entities. ### 3.3. Active Patterns * **Do This:** Use descriptive names for active patterns indicating what the pattern matches. * **Why:** Active patterns are a powerful feature in F#, and clear naming is essential for understanding their purpose. * **Example:** """fsharp let (|Even|_|) input = if input % 2 = 0 then Some input else None let (|Positive|_|) input = if input > 0 then Some input else None let processNumber number = match number with | Even positiveNumber -> printfn "Even positive number: %d" positiveNumber | Positive positiveNumber -> printfn "Positive number: %d" positiveNumber | _ -> printfn "Other number" """ * **Don't Do This:** Vague or nondescript names for active patterns. ## 4. Stylistic Consistency ### 4.1. Immutability * **Do This:** Prefer immutable data structures ("let" bindings, records, discriminated unions) over mutable ones ("mutable" keyword, arrays, "ResizeArray"). * **Why:** Immutability simplifies reasoning about code, avoids unexpected side effects, and makes code easier to test and parallelize. * **Example:** """fsharp // Immutable let numbers = [ 1; 2; 3; 4; 5 ] let doubledNumbers = List.map (fun x -> x * 2) numbers // Mutable (Avoid this unless necessary) let mutable counter = 0 counter <- counter + 1 """ * **Don't Do This:** Using mutable state unnecessarily, which can lead to bugs and make code harder to understand. ### 4.2. Pattern Matching * **Do This:** Use pattern matching extensively for deconstructing data structures and handling different cases. * **Why:** Pattern matching is a concise and expressive way to handle different data scenarios. It also helps the compiler verify that all possible cases are handled. * **Example:** """fsharp type Result<'T, 'Error> = | Success of 'T | Failure of 'Error let processResult result = match result with | Success value -> printfn "Success: %A" value | Failure error -> printfn "Failure: %A" error """ * **Don't Do This:** Using nested "if-else" statements when pattern matching would be clearer. Ignoring compiler warnings about incomplete pattern matches. ### 4.3. Function Composition * **Do This:** Leverage function composition (">>", "<<") to create complex operations from simpler functions. * **Why:** Function composition promotes modularity and reusability. * **Example:** """fsharp let addOne x = x + 1 let multiplyByTwo x = x * 2 let addOneAndMultiplyByTwo = addOne >> multiplyByTwo let result = addOneAndMultiplyByTwo 5 // result = 12 """ * **Don't Do This:** Writing overly complex functions that could be more easily expressed as a composition of smaller functions. ### 4.4. Error Handling * **Do This:** Use "Result<'T, 'Error>" types, "Option<'T>" types, or exceptions appropriately for error handling. * **Why:** Explicit error handling makes code more robust and easier to maintain. * **Example:** """fsharp // Using Result<'T, 'Error> let tryDivide x y = if y = 0 then Failure "Cannot divide by zero" else Success (x / y) match tryDivide 10 0 with | Success result -> printfn "Result: %d" result | Failure error -> printfn "Error: %s" error // Using Option<'T> let tryFind userList userId = userList |> List.tryFind (fun u -> u.Id = userId) match tryFind userList 123 with | Some user -> printfn "User found: %A" user | None -> printfn "User not found" """ * **Don't Do This:** Ignoring potential errors or relying solely on exceptions without proper handling. ### 4.5. Asynchronous Programming * **Do This:** Use "async" workflows for asynchronous operations. Prefer "Async.AwaitTask" for interoperating with .NET "Task" based APIs. * **Why:** "async" workflows provide a structured way to write asynchronous code and avoid callback hell. * **Example:** """fsharp let downloadDataAsync url = async { try let webRequest = System.Net.WebRequest.Create(url) use! response = webRequest.GetResponseAsync() |> Async.AwaitTask use stream = response.GetResponseStream() use reader = new System.IO.StreamReader(stream) let! data = reader.ReadToEndAsync() |> Async.AwaitTask return data with | ex -> printfn "Error downloading data: %s" (ex.Message) return "" } Async.RunSynchronously (downloadDataAsync "https://example.com/data") """ * **Don't Do This:** Blocking the main thread with synchronous operations, or using raw threads directly. ### 4.6. LINQ Style Operations * **Do This:** Favor F#'s built-in collection functions ("List.map", "List.filter", "Seq.groupBy", etc.) over LINQ's extension methods where possible unless you have very specific performance needs. * **Why:** These functions are idiomatic F# and often provide better performance and type safety. * **Example:** """fsharp // Correct let numbers = [ 1; 2; 3; 4; 5 ] let evenNumbers = numbers |> List.filter (fun x -> x % 2 = 0) // Less Idiomatic, unless very specific .NET interop is needed. open System.Linq let evenNumbersLinq = Enumerable.Where(numbers, fun x -> x % 2 = 0) |> Seq.toList """ * **Don't Do This:** Relying on LINQ unnecessarily, especially when similar functionality exists within the F# core libraries ### 4.7. Units of Measure * **Do This**: Use units of measure where appropriate to prevent dimensional analysis errors. * **Why**: Adds a layer of type-safety and prevents common mistakes that can occur in numerical computations. * **Example**: """fsharp [<Measure>] type km [<Measure>] type hr let speed (distance : float<km>) (time : float<hr>) : float<km/hr> = distance / time let distance = 100.0<km> let time = 2.0<hr> let calculatedSpeed = speed distance time // val calculatedSpeed : float<km/hr> = 50.0 """ * **Don't Do This**: Performing calculations on raw numbers without associating units of measure or ignoring compiler warnings related to unit mismatches ### 4.8. Record Updates * **Do This**: Use the "with" keyword for immutable record updates. * **Why**: This creates a new record with the specified fields updated while maintaining immutability, preventing side effects and improving code reliability. * **Example**: """fsharp type Person = { Name: string; Age: int } let person = { Name = "Alice"; Age = 30 } let updatedPerson = { person with Age = 31 } // Creates a new person with Age updated to 31 """ * **Don't Do This**: Avoid mutating record fields directly if the record is defined without "mutable", as this violates immutability principles. ## 5. Documentation ### 5.1. API Documentation * **Do This:** Document all public types, modules, and functions with triple-slash comments ("///"). * **Why:** API documentation is essential for understanding how to use a library or component. * **Example:** """fsharp /// <summary> /// Calculates the area of a rectangle. /// </summary> /// <param name="width">The width of the rectangle.</param> /// <param name="height">The height of the rectangle.</param> /// <returns>The area of the rectangle.</returns> let calculateArea width height = width * height """ * **Don't Do This:** Lack of API documentation. Relying on users to read the code to understand its purpose. ### 5.2. Internal Comments * **Do This:** Use comments to explain complex or non-obvious logic within functions. Use single-line comments ("//") for shorter explanations and multi-line comments ("(* ... *)") for longer explanations. * **Why:** Comments help readers understand the intent and reasoning behind the code. * **Example:** """fsharp let calculateDiscountedPrice originalPrice discountRate = // Calculate the discount amount let discountAmount = originalPrice * discountRate // Subtract the discount from the original price let discountedPrice = originalPrice - discountAmount discountedPrice """ * **Don't Do This:** Over-commenting obvious code, or neglecting to comment complex code. Comments should explain the *why* not just the *what*. ## 6. Tooling & Integration with AI Assistants ### 6.1. Use of ".editorconfig" * **Do This:** Include an ".editorconfig" file in your project to enforce consistent code style across different editors. * **Why:** Ensures that all developers and AI assistants adhere to the same formatting rules, regardless of their preferred editor or IDE. * **Example:** """ini root = true [*] indent_style = space indent_size = 4 end_of_line = lf charset = utf-8 trim_trailing_whitespace = true insert_final_newline = true [*.fs] insert_space_after_comma = true """ * **Don't Do This:** Ignoring editor configuration, allowing inconsistent styling. ### 6.2. Compiler Warnings as Errors * **Do This:** Configure the build process to treat compiler warnings as errors. * **Why:** This forces developers and AI assistants to address potential issues early, preventing them from becoming more serious problems later. * **How:** This depends on the build system. With "dotnet build": "<TreatWarningsAsErrors>true</TreatWarningsAsErrors>" should be included in the ".fsproj" files. * **Don't Do This:** Ignoring compiler warnings, especially those related to pattern matching or unused variables. ### 6.3. Integration with AI Assistants * **Guideline:** Encourage developers and configure CI/CD Pipelines to use tools like GitHub Copilot or similar and train them using your existing documentation and coding standards. This provides a contextual awareness for the tool. * **Why:** AI tools can help enforce code style and conventions automatically, freeing up developers to focus on more complex tasks. However, they must be trained to work with the current conventions. * **How:** * Provide this coding standards document as context to the AI assistant. * Train the AI assistant with examples of good-quality code that adheres to these standards. * Use the AI assistant's suggestions as a starting point, but always review and refine the code to ensure it meets the required standards. * When using AI, always verify and validate the generated code, especially for security-sensitive parts. * **Don't Do This:** Blindly accepting AI-generated code without review. By following these coding standards, F# projects can achieve a high level of consistency, readability, and maintainability, facilitating collaboration, reducing errors, and enabling the effective use of AI-powered coding assistants. This makes adapting to change, performance optimizations, and overall increased security are much more likely.

# Core Architecture Standards for F# This document outlines the core architectural standards for F# development. It aims to provide guidelines for structuring projects, organizing code, and applying architectural patterns to ensure maintainability, scalability, and performance. These standards are designed for modern F# development and incorporate recent language features and ecosystem best practices. ## 1. Fundamental Architectural Patterns This section outlines the fundamental architectural patterns recommended for F# projects. ### 1.1 Functional Core, Imperative Shell **Rationale:** This pattern isolates business logic into a purely functional core, enabling testability and composability. The imperative "shell" handles side effects like I/O, database interactions, and UI updates. **Do This:** * Encapsulate all business logic within F# modules and functions that are free from side effects. * Use discriminated unions and record types to model domain data. * Orchestrate the functional core from an imperative shell that handles external interactions. **Don't Do This:** * Mix side-effecting code directly within core business logic. * Rely on mutable state within the functional core. * Pass external dependencies directly into the core. Use functions instead. **Example:** """fsharp // Functional Core module OrderProcessing = type Order = { OrderId : int CustomerId : int Items : string list TotalAmount : decimal } type OrderError = | InvalidOrder | InsufficientStock let validateOrder (order: Order) : Result<Order, OrderError> = if order.TotalAmount > 0m && order.Items.Length > 0 then Ok order else Error InvalidOrder let calculateTotal (order: Order) : decimal = order.Items |> List.length |> decimal * 10.0m // Imperative Shell module OrderService = open OrderProcessing let processOrder (order: Order) = match validateOrder order with | Ok validOrder -> // Simulate database interaction printfn "Saving order to database: %A" validOrder // Simulate stock update printfn "Updating stock levels for order: %A" validOrder Ok validOrder | Error error -> printfn "Order processing failed: %A" error Error error let createOrder (orderId: int) (customerId: int) (items: string list) : Order = { OrderId = orderId; CustomerId = customerId; Items = items; TotalAmount = calculateTotal { OrderId = orderId; CustomerId = customerId; Items = items; TotalAmount = 0.0m } } // Usage (in a separate application layer or main program) let order = OrderService.createOrder 123 456 ["Item1"; "Item2"] let result = OrderService.processOrder order match result with | Ok _ -> printfn "Order processed successfully" | Error _ -> printfn "Order processing failed" """ **Anti-Patterns:** * **Tight Coupling:** Directly instantiating external dependencies (e.g., database connections) within the functional core. Use dependency injection techniques (see below). * **Impure Functions:** Functions that rely on or modify global state. ### 1.2 Onion Architecture **Rationale:** Onion Architecture promotes loose coupling and testability by placing domain logic at the core and surrounding it with layers of infrastructure concerns. **Do This:** * Define core domain entities and use cases in an inner layer. * Implement interfaces for infrastructure services (e.g., data access, messaging) in the inner layer. * Create concrete implementations of these interfaces in outer layers. * Use dependency injection to provide implementations to the core. **Don't Do This:** * Allow outer layers to depend directly on inner layers. * Embed infrastructure concerns within core domain logic. **Example:** """fsharp // Core (Domain) Layer module Domain = type Order = { OrderId : int CustomerId : int Items : string list } type IOrderRepository = abstract member GetOrder : int -> Order option abstract member SaveOrder : Order -> unit type OrderService(orderRepository: IOrderRepository) = member this.GetOrder(orderId: int) = orderRepository.GetOrder orderId // Infrastructure Layer module Infrastructure = open Domain type OrderRepository() = interface IOrderRepository with member this.GetOrder (orderId: int) = // Simulate database retrieval if orderId = 123 then Some { OrderId = 123; CustomerId = 456; Items = ["Item1"; "Item2"] } else None member this.SaveOrder (order: Order) = // Simulate saving to database printfn "Saving order to database: %A" order // Application Layer (Composition Root) module Application = open Domain open Infrastructure let orderRepository = OrderRepository() :> IOrderRepository let orderService = OrderService(orderRepository) let getOrder (orderId: int) = orderService.GetOrder orderId // Usage let order = Application.getOrder 123 match order with | Some o -> printfn "Order: %A" o | None -> printfn "Order not found" """ **Anti-Patterns:** * **Layer Violations:** An outer layer directly accessing an inner layer's implementation details. * **God Class:** Centralizing too much logic in a single, massive class. ### 1.3 Microservices Architecture **Rationale:** Decomposing a large application into smaller, independent services promotes scalability, fault isolation, and independent deployments. **Do This:** * Define clear boundaries between microservices based on business capabilities. * Use asynchronous communication (e.g., message queues) for inter-service communication. * Design each service to be independently deployable and scalable. * Implement robust error handling and monitoring for each service. **Don't Do This:** * Create tightly coupled microservices that depend heavily on each other. * Share databases between microservices. * Over-engineer communication protocols. **Example (Simplified):** """fsharp // Order Service module OrderService = open System open System.Threading.Tasks let processOrder (orderId: int) : Task<string> = Task.Run(fun () -> // Simulate order processing printfn "Processing order %d in OrderService" orderId Task.Delay(1000) |> Async.AwaitTask |> Async.RunSynchronously sprintf "Order %d processed successfully" orderId) // Notification Service module NotificationService = open System open System.Threading.Tasks let sendNotification (message: string) : Task<unit> = Task.Run(fun () -> // Simulate sending notification printfn "Sending notification: %s in NotificationService" message Task.Delay(500) |> Async.AwaitTask |> Async.RunSynchronously ()).Ignore() // Orchestration (e.g., using a message queue) module Orchestration = open OrderService open NotificationService let handleOrderRequest (orderId: int) = processOrder orderId |> Async.AwaitTask |> Async.map (fun result -> sendNotification result |> ignore ) |> Async.RunSynchronously // Usage (simulated message queue trigger) Orchestration.handleOrderRequest 456 """ **Anti-Patterns:** * **Distributed Monolith:** Decomposing an application into microservices without proper bounded contexts. * **Chatty Services:** Excessive inter-service communication that introduces latency and complexity. ## 2. Project Structure and Organization This section describes the recommended layout for F# projects. ### 2.1 File Organization **Rationale:** A well-organized file structure improves code discoverability and maintainability. **Do This:** * Organize files by logical modules or components. * Use folders to group related files. * Name files according to the module or type they contain (e.g., "Order.fs", "OrderService.fs"). * Place interface definitions in separate files ("IOrderRepository.fs"). * Within a file, order declarations as: types, then functions depending on those types. Circular dependencies are an anti-pattern to be avoided. **Don't Do This:** * Place unrelated code in the same file. * Use excessively long or cryptic filenames. * Create deeply nested folder structures without clear purpose. **Example:** """ MyProject/ ├── Domain/ │ ├── Order.fs │ ├── Customer.fs │ └── Types.fs ├── Infrastructure/ │ ├── OrderRepository.fs │ ├── DatabaseContext.fs │ └── MessagingService.fs ├── Application/ │ ├── OrderService.fs │ └── CustomerService.fs ├── API/ │ ├── Controllers/ │ │ ├── OrderController.fs │ │ └── CustomerController.fs │ ├── Models/ │ │ ├── OrderModel.fs │ │ └── CustomerModel.fs │ └── Program.fs (or Startup.fs) └── MyProject.fsproj """ ### 2.2 Module Structure **Rationale:** Modules provide namespaces and encapsulation for F# code. **Do This:** * Use modules to group related functions and types. * Name modules according to their purpose. * Use nested modules to create hierarchies of functionality. * Consider making the module a type (record type, single case discriminated union) so it can be passed as a value. **Don't Do This:** * Create overly large modules that are difficult to navigate. * Use vague or confusing module names. * Expose internal implementation details through module exports. **Example:** """fsharp module MyModule = type MyType = { Value : int } let myFunction (x: MyType) = x.Value * 2 module Internal = let hiddenFunction x = x + 1 // Not exposed outside MyModule """ ### 2.3 Solution Structure **Rationale:** A well-structured solution facilitates code reuse and project management. **Do This:** * Divide a large application into multiple projects based on logical boundaries. * Create separate projects for core domain logic, infrastructure concerns, and UI. * Use a dedicated project for unit tests. * Consider using a "Shared" or "Common" project for utility functions and shared types. **Don't Do This:** * Create a single massive project for the entire application. * Mix unrelated code in the same project. * Create circular project dependencies. **Example:** """ MySolution/ ├── MyProject.Core/ (Domain Logic) ├── MyProject.Infrastructure/ (Data Access, Messaging) ├── MyProject.API/ (Web API) ├── MyProject.Tests/ (Unit Tests) └── MySolution.sln """ ## 3. Dependency Management and Inversion of Control This section covers dependency management techniques in F#. ### 3.1 Dependency Injection **Rationale:** Dependency Injection (DI) promotes loose coupling and testability by providing dependencies to components rather than having them create their own. **Do This:** * Use constructor injection to provide dependencies to types. * Define interfaces for dependencies to abstract away concrete implementations. * Use a DI container (e.g., .NET's built-in DI container, Autofac) to manage dependency resolution (required for larger projects, adds some initial cognitive overhead). * Consider Reader monad as an alternative to traditional DI. **Don't Do This:** * Use the 'new' keyword directly within components to create dependencies. * Create static dependencies. * Pass too many dependencies to a single type (consider refactoring). **Example:** """fsharp open Microsoft.Extensions.DependencyInjection // Interface type IEmailService = abstract member SendEmail : string -> string -> string -> unit // Implementation type EmailService() = interface IEmailService with member this.SendEmail (toAddress: string, subject: string, body: string) = printfn "Sending email to %s with subject %s: %s" toAddress subject body // Component with dependency type MyComponent(emailService: IEmailService) = member this.DoSomething() = emailService.SendEmail "user@example.com" "Important Notification" "Hello, world!" // DI Container setup let serviceCollection = ServiceCollection() serviceCollection.AddSingleton<IEmailService, EmailService>() serviceCollection.AddSingleton<MyComponent>() let serviceProvider = serviceCollection.BuildServiceProvider() // Resolve dependencies let component = serviceProvider.GetService<MyComponent>() // Usage component.DoSomething() """ ### 3.2 Reader Monad **Rationale:** The Reader Monad provides access to an environment or configuration without explicitly passing it to every function. This can be a simpler approach for smaller applications or for managing application configuration. **Do This:** * Define a type representing your dependency/configuration e.g. "type AppConfig = { DbConnectionString: string }" * Create a computation expression builder to manage the Reader context implicitly. * Use the computation expression to access your configuration within the relevant scope. **Don't Do This:** * Avoid using Reader Monad when explicit dependency injection via constructors provides clearer explicitness. * Overuse of Reader Monad to hide dependencies, making code harder to understand. **Example:** """fsharp type AppConfig = { DbConnectionString: string } // Computation Expression Builder for Reader Monad type Reader<'Config, 'T> = 'Config -> 'T type ReaderBuilder() = member this.Bind(reader: Reader<'Config, 'a>, func: 'a -> Reader<'Config, 'b>) : Reader<'Config, 'b> = fun config -> func (reader config) config member this.Return(value: 'T) : Reader<'Config, 'T> = fun _ -> value member this.ReturnFrom(reader: Reader<'Config, 'T>) : Reader<'Config, 'T> = reader member this.Zero() : Reader<'Config, unit> = fun _ -> () member this.Delay(func: unit -> Reader<'Config, 'T>) : Reader<'Config, 'T> = fun config -> (func ()) config member this.Run(reader: Reader<'Config, 'T>, config: 'Config) : 'T = reader config let reader = ReaderBuilder() // Code using the Reader Monad let getConfigValue key (config: AppConfig) = match key with | "ConnectionString" -> config.DbConnectionString | _ -> failwith "Unknown Configuration Key" let readDbData : Reader<AppConfig, string> = reader { let connectionString = getConfigValue "ConnectionString" return $"Reading data from {connectionString}" } // Application Code let appConfig = { DbConnectionString = "Server=localhost;Database=MyDb" } let data = reader.Run(readDbData, appConfig) printfn "%s" data """ ## 4. Error Handling This section focuses on robust error handling practices in F#. ### 4.1 Result Type **Rationale:** The "Result" type provides a clear and explicit way to represent operations that can succeed or fail. **Do This:** * Use the "Result<'T, 'Error>" type (or a custom discriminated union for more specific errors) to represent fallible operations. * Handle both success and failure cases explicitly using pattern matching. * Use "Result.bind" to chain operations that return "Result" values. **Don't Do This:** * Throw exceptions for expected errors. Exceptions should be reserved for truly exceptional circumstances (e.g., out-of-memory errors). * Ignore the "Error" case in a "Result" value. **Example:** """fsharp type ValidationError = | EmptyString | InvalidFormat let validateString (input: string) : Result<string, ValidationError> = if String.IsNullOrEmpty input then Error EmptyString elif input.Length < 5 then Error InvalidFormat // Example validation else Ok input let processString (validatedString: string) : Result<string, string> = try // Simulate processing Ok($"Processed: {validatedString.ToUpper()}") with _ -> Error "Processing Error" let validated = validateString "validString" let processed = Result.bind processString validated match processed with | Ok result -> printfn "Result: %s" result | Error error -> printfn "Error: %A" error """ ### 4.2 Exception Handling **Rationale:** Exceptions should be used sparingly for truly exceptional circumstances and handled carefully. **Do This:** * Use "try...with" blocks to catch and handle exceptions. * Log exceptions with meaningful context. * Avoid catching generic "Exception" unless absolutely necessary. * Consider using custom exception types for specific error conditions. **Don't Do This:** * Use exceptions for flow control. * Swallow exceptions without logging or handling them appropriately. * Rethrow exceptions without preserving the original stack trace (use "reraise()" in "use" blocks for proper resource disposal). **Example:** """fsharp open System try // Code that might throw an exception let result = 10 / 0 printfn "Result: %d" result with | :? DivideByZeroException -> printfn "Error: Division by zero" | ex -> printfn "An unexpected error occurred: %s" ex.Message """ ### 4.3 Asynchronous Error Handling **Rationale:** Asynchronous operations require special consideration for error handling using "AsyncResult". **Do This:** * Use "AsyncResult" to propagate success and failure through asynchronous workflows. * Handle exceptions within "async" blocks using "try...with". * Use "Async.Catch" to turn an "async" computation into a "Result" that signals errors (especially interacting with .NET libraries.) **Don't Skip:** * Forgetting to consider asynchronous error handling. This leads to unhandled exceptions crashing the application. **Example:** """fsharp open System let fetchUserDataAsync (userId: int): Async<Result<string, string>> = async { try // Simulate fetching user data if userId = 1 then return Ok "User Data" else failwith "User not found" with | ex -> return Error (ex.Message) } let processUserDataAsync (result: Result<string, string>): Async<unit> = async { match result with | Ok data -> printfn "User data: %s" data | Error err -> printfn "Error: %s" err } let workflow userId = fetchUserDataAsync userId |> Async.Bind processUserDataAsync Async.RunSynchronously (workflow 1) Async.RunSynchronously (workflow 2) """ ## 5. Conclusion These core architecture standards for F# offer a robust foundation for building maintainable, scalable, and performant applications. Adhering to these guidelines will promote consistency within development teams and facilitate the creation of high-quality F# code. Regularly review and adapt these standards to remain aligned with evolving best practices and project-specific needs.

# Component Design Standards for F# This document outlines the component design standards for F# development, aimed at creating reusable, maintainable, and high-performance components. These standards are based on best practices, the latest F# version features, and insights from the F# community. ## 1. General Principles * **Do This**: Embrace functional principles: immutability, composition, and pure functions. * **Why**: This fosters easier reasoning about code, simplifies testing, and reduces the likelihood of side effects which can lead to bugs. Components built on these principles promotes reusability and scalability. * **Don't Do This**: Rely heavily on mutable state within core component logic. Avoid complex object hierarchies where possible. * **Why**: Mutable state makes reasoning about code difficult. Object hierarchies can lead to tight coupling and reduce reusability. * **Do This**: Design for testability from the start. Make components easily injectable and mockable. * **Why**: Testing is critical for maintainability. Components that are designed with testability in mind are easier to verify and refactor. * **Don't Do This**: Create components with tight dependencies on external systems or libraries that are difficult to mock or replace. * **Why**: This makes testing more difficult and limits the component's reusability. * **Do This**: Prioritize clarity and expressiveness in your code. Use meaningful names and clear comments. * **Why**: Readable code is maintainable code. Expressive code reduces cognitive load and makes it easier for others to understand and contribute. * **Don't Do This**: Sacrifice readability for the sake of brevity. Opaque or overly clever code is difficult to maintain. ## 2. Abstraction and Interfaces * **Do This**: Use interfaces (abstract classes or F# interfaces) to define contracts between components for broader interoperability and testability. * **Why**: Interfaces decouple components, allowing for independent development, testing, and evolution. They enforce a standard contract for interactions. * **Example**: """fsharp // Defining an interface type IDataService = abstract member GetData : string -> Result<string, string> // Implementation of the interface type DataService() = interface IDataService with member this.GetData (key: string) = try // Simulate fetching data (replace with real implementation) if key = "validKey" then Ok "Data fetched successfully" else Error "Key not found" with | ex -> Error ex.Message // Using the interface let processData (service: IDataService) (key: string) = match service.GetData key with | Ok data -> printfn "Data: %s" data | Error error -> printfn "Error: %s" error // Example usage let service = DataService() :> IDataService // explicit upcast processData service "validKey" processData service "invalidKey" """ * **Don't Do This**: Expose concrete implementation details through interfaces. * **Why**: This defeats the purpose of abstraction and can lead to tight coupling. * **Do This**: Prefer discriminated unions for representing data across component boundaries when appropriate, especially when defining a finite set of possibilities. * **Why**: Discriminated unions provide type safety and exhaustiveness checks. They are highly suitable for representing different states or categories of data. * **Example**: """fsharp type Result<'T, 'Error> = | Success of 'T | Failure of 'Error // Using the interface let processResult (result: Result<string, string>) = match result with | Success data -> printfn "Data: %s" data | Failure error -> printfn "Error: %s" error // Implementing a function using the discriminated union let fetchData (key: string) : Result<string, string> = if key = "validKey" then Success "Data fetched successfully" else Failure "Key not found" // Example usage processResult (fetchData "validKey") processResult (fetchData "invalidKey") """ * **Don't Do This**: Use inheritance excessively. Prefer composition over inheritance. * **Why**: Inheritance can lead to fragile base class problems and tight coupling. Composition provides greater flexibility and promotes code reuse. ## 3. Error Handling * **Do This**: Use "Result<'T, 'Error>" to handle errors explicitly. Represent success and failure paths clearly. * **Why**: Explicit error handling improves code clarity and prevents unexpected exceptions and null reference exceptions. Forces callers to handle potential failure scenarios. * **Example**: """fsharp let divide x y : Result<float, string> = if y = 0.0 then Error "Cannot divide by zero" else Ok (x / y) match divide 10.0 2.0 with | Ok result -> printfn "Result: %f" result | Error message -> printfn "Error: %s" message """ * **Don't Do This**: Rely solely on exceptions for control flow. Exceptions should be reserved for exceptional circumstances. * **Why**: Excessive use of exceptions for control flow is inefficient and makes code harder to reason about. Avoid throwing exceptions to indicate normal, expected outcomes. * **Do This**: Log errors and warnings with sufficient context, including timestamps, user information (if available), and relevant data. Use structured logging when possible. * **Why**: Good logging is crucial for debugging and monitoring the health of components. * **Don't Do This**: Log sensitive information (passwords, API keys, etc.) or personally identifiable information (PII). * **Why**: Security and privacy. * **Do This**: Consider using custom exception types for failures that need special contextual information. * **Why**: Allows catching specific errors to handle them appropriately. * **Don't Do This**: Rethrow exceptions without adding context, masking the true place of the exception. ## 4. Immutability and Pure Functions * **Do This**: Make data immutable by default using "let" bindings and immutable data structures (records, lists, sets, maps). * **Why**: Immutability simplifies reasoning about code, prevents unintended side effects, and improves concurrency safety. * **Example**: """fsharp type Person = { Name: string; Age: int } let createPerson name age = { Name = name; Age = age } let updateAge person newAge = { person with Age = newAge } let person1 = createPerson "Alice" 30 let person2 = updateAge person1 31 // Returns a new Person record """ * **Don't Do This**: Use mutable variables ("mutable" keyword) unless absolutely necessary. If you must use mutation, isolate it within a small, well-defined scope. * **Why**: Mutable state introduces complexity and potential for errors. * **Do This**: Write pure functions whenever possible. A pure function always returns the same output for the same input and has no side effects. * **Why**: Pure functions are easy to test, compose, and reason about. They promote code reuse and modularity. * **Example**: """fsharp let add x y = x + y // Pure function let result = add 5 3 // Always returns 8 """ * **Don't Do This**: Create functions that modify external state or rely on external state that can change unexpectedly. * **Why**: These functions are harder to test and reason about. ## 5. Asynchronous Programming * **Do This**: Use "async" workflows for asynchronous operations involving I/O or long-running computations. * **Why**: Asynchronous programming prevents blocking the main thread, improving responsiveness and scalability. * **Example**: """fsharp open System.Net.Http let fetchContent url = async { use client = new HttpClient() let! response = client.GetStringAsync(url) |> Async.AwaitTask return response } // Execute the asynchronous operation let task = fetchContent "https://example.com" let content = Async.RunSynchronously task printfn "%s" content """ * **Don't Do This**: Block the main thread with synchronous I/O operations. * **Why**: This can lead to unresponsiveness and performance problems. * **Do This**: Handle exceptions within "async" workflows using "try...with". * **Why**: To prevent unhandled exceptions from crashing the application. * **Don't Do This**: Use "Async.RunSynchronously" in UI threads. It leads to deadlocks. * **Do This**: Use "Task<'T>" and ".NET" concurrent collections when interacting with ".NET" libraries. * **Why**: Increases interoperability with ".NET" ecosystem allowing to use F# in mixed ".NET"/F# solutions. ## 6. Naming Conventions * **Do This**: Use descriptive and meaningful names for types, functions, and variables. * **Why**: Good naming improves code readability and understandability. * **Don't Do This**: Use abbreviations or cryptic names that are difficult to understand. * **Do This**: Follow these conventions: * Types: PascalCase (e.g., "DataService", "Person") * Functions: camelCase (e.g., "getData", "calculateTotal") * Variables: camelCase (e.g., "name", "age") * Parameters: camelCase (e.g., "input", "value") * Modules: PascalCase (e.g., "DataModule", "MathUtils") * **Don't Do This**: Deviate from established naming conventions. * **Do This**: Use plural names for collections (e.g., "customers", "products"). * **Why**: This clearly communicates that the variable represents a collection. ## 7. Dependency Injection * **Do This**: Use dependency injection to provide components with their dependencies. * **Why**: Dependency injection promotes loose coupling, making components more testable and reusable. * **Don't Do This**: Hardcode dependencies within components. * **Do This**: Use constructor injection to provide dependencies. * **Why**: Constructor injection makes dependencies explicit and ensures that components receive their required dependencies. * **Example:** """fsharp type OrderProcessor (dataService: IDataService, emailService: IEmailService) = member this.ProcessOrder (orderId: string) = match dataService.GetData orderId with | Ok orderData -> emailService.SendConfirmationEmail(orderData.CustomerEmail, orderId) Ok () | Error error -> Error error """ * **Don't Do This**: Expose setter properties for dependencies (property injection) unless there is a specific reason to do so. Constructor injection is preferable. * **Do This**: Favor interfaces for dependencies to make mocking easier and allow for multiple implementations. ## 8. Performance * **Do This**: Use immutable data structures efficiently. When modifying collections, consider using persistent data structures or specialized mutable collections when performance is critical. * **Why**: Immutability is generally good but might has performance penalties in specific scenarios. * **Don't Do This**: Create excessive copies of large data structures unnecessarily. * **Do This**: Measure and profile code to identify performance bottlenecks. Use performance testing tools like BenchmarkDotNet. * **Why**: To identify and optimize performance-critical sections of code. * **Don't Do This**: Make premature optimizations without measuring performance. * **Do This**: Use tail recursion optimization to prevent stack overflows in recursive functions. * **Why**: Improves performance and prevents stack overflow errors. * **Example**: """fsharp // Tail-recursive function let rec factorial n acc = if n = 0 then acc else factorial (n - 1) (n * acc) let result = factorial 5 1 // Initial accumulator value is 1 // Non-tail-recursive function (will cause StackOverflowException for large n) let rec factorialNonTailRecursive n = if n = 0 then 1 else n * factorialNonTailRecursive (n - 1) """ * **Don't Do This:** Implement recursive functions without taking tail recursion into account. ## 9. Security * **Do This**: Parameterize queries and commands to prevent SQL injection. * **Why**: Prevents malicious code injection into database queries. * **Don't Do This**: Construct SQL queries using string concatenation with user-supplied input. * **Do This**: Sanitize user input to prevent cross-site scripting (XSS) attacks. * **Why**: Prevents malicious scripts from being injected into web pages. * **Don't Do This**: Display unsanitized user input directly on web pages. * **Do This**: Use appropriate authentication and authorization mechanisms to protect sensitive data and functionality. * **Why**: Ensures that only authorized users can access specific resources. * **Don't Do This**: Store passwords in plain text. Use strong hashing algorithms with salting. * **Do This**: Avoid using deprecated or vulnerable libraries. Keep dependencies up to date. * **Why**: To inherit the best security patches for the known vulnerabilities. * **Don't Do This**: Blindly trust external dependencies. Review security advisories and assess risks. ## 10. Documentation * **Do This**: Provide clear and concise documentation for all public types, functions, and modules. * **Why**: Documentation makes components easier to understand and use. * **Don't Do This**: Omit documentation or provide inadequate documentation. * **Do This**: Use F# signature files (".fsi") to define public interfaces and document them. * **Why**: Signature files provide a clear contract for the public API of a component. * **Don't Do This**: Expose implementation details in signature files. * **Do This**: Include examples of how to use components in the documentation. * **Why**: Examples make it easier for users to get started with the component. * **Don't Do This**: Provide outdated or incorrect examples. * **Do This**: Document any known limitations or potential issues with components. * **Why**: Transparency builds trust and helps users avoid common pitfalls. ## 11. Tooling * **Do This**: Use a code formatter (e.g., Fantomas) to ensure consistent code formatting. * **Why**: Consistent formatting improves code readability and reduces visual noise. * **Don't Do This**: Rely on manual formatting or inconsistent formatting styles. * **Do This**: Use a code analyzer (e.g., FSharpLint) to identify potential issues and enforce coding standards. * **Why**: Code analyzers help catch errors and enforce best practices early in the development process. * **Don't Do This**: Ignore warnings or errors reported by code analyzers. * **Do This**: Integrate testing into the build process. * **Why**: Ensures that tests are run automatically whenever code is changed. * **Don't Do This**: Skip testing or rely on manual testing. * **Do This**: Familiarize yourself with the F# compiler options and use them to optimize code generation. ## 12. Specific F# Patterns and Anti-Patterns * **Do This**: Use computation expressions for complex control flow, asynchronous programming, or working with monads. * **Why**: Computation expressions provide a concise and readable way to express complex logic. * **Example**: """fsharp type MaybeBuilder() = member this.Bind(x, f) = match x with | Some v -> f v | None -> None member this.Return(x) = Some x member this.ReturnFrom(x) = x member this.Zero() = None let maybe = MaybeBuilder() let divide x y = if y = 0 then None else Some (x / y) let result = maybe { let! a = divide 10 2 let! b = divide a 5 return b } printfn "%A" result """ * **Don't Do This**: Overuse computation expressions for simple operations. * **Do This**: Utilize pattern matching extensively for data decomposition and control flow. * **Why**: Pattern matching provides a powerful and expressive way to work with discriminated unions and other data types. * **Don't Do This**: Use nested "if...then...else" statements excessively. Pattern matching is often a better alternative. * **Do This**: When using "Seq.fold" or "List.fold", pay attention to the order of arguments. * **Why**: "Seq.fold"'s accumulator receives the current state as its first argument, while the current element is the second argument. * **Don't Do This**: Confuse arguments leading to incorrect state and calculation. This comprehensive document provides a strong foundation for building robust, maintainable, and scalable F# components. Adhering to these standards improves code quality, reduces errors, and promotes collaboration within development teams. By following these guidelines, development teams ensures its resulting code base is built to industry standards.

# State Management Standards for F# This document outlines coding standards for state management in F#. It emphasizes maintainability, performance, and security while leveraging modern F# features and best practices. These guidelines are designed to direct developers, act as a reference for code reviews, and inform AI coding assistants. ## 1. Architectural Approaches to State Management ### 1.1. Functional Core, Imperative Shell **Standard:** Employ a "Functional Core, Imperative Shell" architecture. * **Do This:** Isolate all business logic and state transformations within pure functions in the core. Keep the outer layers which interact with the outside world (UI, database, network) minimal and handle only necessary side effects. * **Don't Do This:** Embed complex logic or state mutations directly within event handlers or UI components, leading to tight coupling and testability issues. **Why:** This approach promotes testability, reusability, and maintainability. The functional core becomes easy to unit test since it has no side effects. The imperative shell can be more challenging to test, but is minimized in scope. **Example:** """fsharp // Functional Core (pure functions) module Core = let calculateNewState currentState input = // Compute next state based on current application state and input // Example: { currentState with Value = currentState.Value + input } // Imperative Shell (event handler) module UI = open Core // Accessing the functional core let handleButtonClick currentState input = let newState = Core.calculateNewState currentState input // Update the UI with the newState (a side effect) // Example (pseudo-code): // uiElement.Text <- newState.Value.ToString() newState """ ### 1.2. Explicit State Management **Standard:** Favor explicit state management over implicit, hidden state. * **Do This:** Clearly define the state structure within record types or discriminated unions. * **Don't Do This:** Rely on mutable variables scattered throughout the codebase or hidden within closures without a clearly defined structure. **Why:** Explicit state makes the system behavior more predictable and easier to reason about. It avoids unexpected side effects from seemingly unrelated sections of code. **Example:** """fsharp // Explicit state using a record type type AppState = { Counter: int IsLoading: bool Data: string option } // Implicit (avoid): let mutable counter = 0 // Avoid this for central state """ ### 1.3. Data Flow Direction **Standard:** Establish a clear, unidirectional data flow. * **Do This:** Define how state changes originate, how they propagate through the system, and how the UI or other parts of the application react to these changes. * **Don't Do This:** Allow bi-directional data dependencies, where components directly modify each other's state, leading to unpredictable cycles and difficulty in debugging. **Why:** The unidirectional flow enforces a more organized structure and simplified auditing changes to the state. **Example:** (Illustrative) """ // State --(Action)--> State --(View)--> State (Unidirectional) // Contrast this to: // State <-----> State (Bidirectional, Avoid!) """ ## 2. State Management Patterns ### 2.1. Model-View-Update (MVU) **Standard:** Consider the MVU architecture for UI-driven applications. * **Do This:** Structure the application state as a single, immutable model. Define a set of messages/actions that can update the model. Implement an "update" function which takes the current model and a message, and returns a new model. The view function translates the model into the user interface, possibly dispatching actions based on user interactions. * **Don't Do This:** Directly manipulate the UI from event handlers or bypass the central update function. **Why:** MVU promotes predictability, simplifies debugging, and enhances testability. It enforces a clear separation of concerns and makes it easy to reason about the application's state transitions. **Example:** (Simplified) """fsharp // Model type Model = { Count: int Text: string } // Messages type Message = | Increment | Decrement | SetText of string // Update function let update (message: Message) (model: Model) = match message with | Increment -> { model with Count = model.Count + 1 } | Decrement -> { model with Count = model.Count - 1 } | SetText text -> { model with Text = text } // View function (pseudo-code) let view (model: Model) (dispatch: Message -> unit) = // Render UI elements based on the model.Dispatch messages on user interaction. // Example: // Button("Increment", onClick = fun () -> Increment |> dispatch) () //Initial model values let initialModel = { Count = 0; Text = ""} """ ### 2.2. Event Sourcing **Standard:** Employ Event Sourcing when the application requires a complete audit log of state changes or the ability to replay past states. * **Do This:** Store a sequence of immutable events representing all state changes in the application. Reconstruct the current state by replaying these events in order. * **Don't Do This:** Directly persist the current state snapshot, losing the history of changes. Be mindful of the trade-off between read performance (requiring event replay) and the benefits of a complete audit log. **Why:** Event Sourcing enables audit logging, temporal queries (querying past states of the application), and facilitates debugging of complex state transitions. It also supports CQRS (Command Query Responsibility Segregation) architectures. **Example:** """fsharp // Event type type Event = | CounterIncremented of int | CounterDecremented of int // Aggregate function (replays events to compute state) let applyEvent (state: int) (event: Event) = match event with | CounterIncremented amount -> state + amount | CounterDecremented amount -> state - amount // Reconstruct state from events let reconstructState (events: Event list) = events |> List.fold applyEvent 0 """ ### 2.3. State Machines **Standard:** Use state machines to model complex, stateful behavior with clearly defined state transitions. * **Do This:** Represent the state transitions using a discriminated union or a graph-based library. Ensure that transitions between states are well-defined and handle all possible input events. * **Don't Do This:** Use nested "if/else" statements or mutable flags to manually manage state transitions – this is error-prone and difficult to maintain. **Why:** State machines provide a structured approach for reasoning complex branching logic and can be formally verified. **Example:** """fsharp // State definition type State = | Idle | Loading | Loaded of Data | Error of string // Event definition type Event = | LoadData | DataLoaded of Data | DataLoadFailed of string // Transition function let transition (event: Event) (state: State) = match state, event with | Idle, LoadData -> Loading | Loading, DataLoaded data -> Loaded data | Loading, DataLoadFailed error -> Error error | _, _ -> state // No transition """ ## 3. Data Structures for State ### 3.1. Immutable Records and Discriminated Unions **Standard:** Prefer immutable records and discriminated unions to represent application state. * **Do This:** Design data structures that accurately reflect the domain and use immutable types for all core data. * **Don't Do This:** Use mutable data structures (e.g., mutable lists/arrays) for directly managing application state. Favor creating a new copy of the data with each modification. **Why:** Immutability simplifies reasoning about the code, prevents unexpected side effects, and makes the application more thread-safe. **Example:** """fsharp // Immutable record type User = { Id: int Name: string Email: string } // Immutable update (create a new copy) let updateUserEmail (user: User) (newEmail: string) = { user with Email = newEmail } // Discriminated Union sample using the Option type type Name = | FirstName of string | MiddleName of string | LastName of string let getLastName (name: Name) : string option = match name with | LastName str -> Some str | _ -> None printfn "%A" (getLastName(LastName "Smith")) """ ### 3.2. Choosing appropriate collection types **Standard:** Use the collection type that best suits the access patterns and performance requirements of the application. * **Do This:** Use "Set", "Map", and "List" from the immutable collections library when appropriate. Understand the performance characteristics (e.g., order of operations, lookup speed) of each data structure. When performance is extremely critical, consider using "Array" from the standard library, but ensure you do not mutate the values. * **Don't Do This:** Overuse mutable collections unless absolutely necessary for performance reasons. Avoid using generic "System.Collections" and "System.Collections.Generic" types, favoring the F#-specific collections. **Why:** By choosing appropriate collection types, an increase in performance can be realized and code can be more expressive, and less error-prone within F#. **Example:** """fsharp //Immutable List let names = ["Alice"; "Bob"; "Charlie"] //Immutable Set let uniqueNames = Set.ofList names //Immutable Map let ages = Map.empty |> Map.add "Alice" 30 |> Map.add "Bob" 25 //Array let numbers : int array = [| 1; 2; 3; 4; 5 |] // Consider using Array only if immutability is guaranteed """ ### 3.3. Consider Persistent Data Structures **Standard:** For very large data sets or scenarios with frequent updates, consider using persistent data structures from libraries like FSharp.Collections. * **Do This:** Understand the advantages and disadvantages of persistent data structures (e.g., structural sharing, amortized efficiency). * **Don't Do This:** Blindly use persistent data structures without understanding their performance characteristics which can lead to unexpected overheads. **Why:** Persistent data structures can reduce memory allocations and improve performance in scenarios where small changes are made to a large data set frequently. ## 4. Asynchronous State Management ### 4.1. Asynchronous Workflows and Agents **Standard:** Manage concurrent state access with asynchronous workflows and agent-based concurrency. * **Do This:** Use "Async.Await" to orchestrate asynchronous operations. Use "MailboxProcessor" (agents) to encapsulate state and coordinate access from multiple threads or asynchronous processes. * **Don't Do This:** Directly manipulate shared mutable state from multiple threads without proper synchronization, leading to race conditions and data corruption. Avoid using locks directly (e.g., "lock obj") unless absolutely necessary, favoring agent-based concurrency. **Why:** Asynchronous workflows provide a structured approache to handling asynchronous code. Agents protect mutable state by serializing access and ensure that state transitions are atomic. **Example:** """fsharp open System open System.Threading.Tasks open FSharp.Control // Agent to manage counter state let counterAgent = MailboxProcessor.Start(fun inbox -> let rec loop (count: int) = async { let! msg = inbox.Receive() match msg with | "Increment" -> printfn "Incrementing counter: %d" (count + 1) return! loop (count + 1) | "GetCount" -> Async.Return(count) |> Async.Await return! loop count | _ -> printfn "Unknown message" return! loop count } loop 0) // Usage counterAgent.Post("Increment") counterAgent.Post("Increment") Task.Delay(1000).Wait() // Wait for agent to process messages let getCountAsync = counterAgent.PostAndReply(fun reply -> "GetCount", reply) let count = Async.RunSynchronously getCountAsync printfn "Final count: %d" count """ ### 4.2. Effect Handlers **Standard:** To handle more complex side-effectful operations such as logging, use effect handlers. * **Do This:** Leverage computation expressions and effect handlers to encapsulate more complex data structures. * **Don't Do This:** Neglecting the use of effect handlers which can lead to complex logic directly within the core functionalities. **Why:** Effect handlers encapsulates more complex stateful operations such as logging, error handling or interacting resources that needs to be taken care of during computation processes. **Example:** """fsharp type LoggerEffect = abstract Log: string -> unit let loggerHandler = { new LoggerEffect with member _.Log(message) = printfn "Log: %s" message } type MyState = { Value: int Logger: LoggerEffect } let myComputation (state: MyState) = state.Logger.Log("Starting process") { state with Value = state.Value + 1 } let initialState = { Value = 0; Logger = loggerHandler } let finalState = myComputation initialState """ ## 5. Testing State Management ### 5.1. Unit Testing Pure Functions **Standard:** Write unit tests for all pure functions involved in state transformations. * **Do This:** Provide a set of input values and verify that the output values are as expected. Use property-based testing frameworks like FsCheck to generate a wide range of test cases automatically. * **Don't Do This:** Neglect unit testing the functions that perform the core state updates. **Why:** This approach ensures that the business logic is correct and operates independently of any side effects. **Example:** """fsharp open Xunit open FsCheck // Unit test for the 'update' function in the MVU example [<Fact>] let ""Increment message should increment the count"" () = let initialModel = { Count = 0; Text = "" } let updatedModel = update Increment initialModel Assert.Equal(1, updatedModel.Count) // Property-based test [<Property>] let ""Incrementing the count should always increase it"" (count: int) = let initialModel = { Count = count; Text = "" } let updatedModel = update Increment initialModel updatedModel.Count > count """ ### 5.2. Integration Testing **Standard:** Design integration tests to verify the interaction between different components of the system and test state management across module boundaries. * **Do This:** Test the entire data flow, from UI interactions that trigger state changes to how the updated state affects other components or is persisted to a database. * **Don't Do This:** Only focus on unit tests, neglecting the bigger picture and failing to identify integration issues. **Why:** Integration tests ensure that different parts of the application work together correctly. ### 5.3. Mocking External Dependencies **Standard:** Mock external dependencies (e.g., databases, APIs) in tests to isolate state management logic. * **Do This:** Use mocking frameworks to simulate external system behaviors and avoid depending on real data. This can be done by creating dummy data. * **Don't Do This:** Directly access external systems in tests, making them slow, unreliable, and hard to set up. **Why:** This ensures that tests are fast and deterministic and focus solely on the logic being tested. It also prevents tests from modifying external systems. ## 6. Security Considerations for State ### 6.1. Input Validation **Standard:** Ensure that all inputs that can modify the system's state are properly validated. * **Do This:** Validate input data to protect against injection attacks, data integrity violations, and denial-of-service vulnerabilities. * **Don't Do This:** Trust the input data without validation. All external sources of state modification must be validated before processing. **Why:** Preventing invalid data from entering the system reduces the number of possible application exploits. ### 6.2. Data Encryption **Standard:** Encrypt sensitive data at rest and in transit to protect against unauthorized access. * **Do This:** Use appropriate encryption algorithms and key management techniques to protect sensitive data. * **Don't Do This:** Store sensitive information in plain text. Securely manage encryption keys. **Why:** Encryption protects data, even if the system is compromised. ### 6.3. Authentication & Authorization **Standard:** Strictly control access to state-modifying operations through proper authentication and authorization mechanisms. * **Do This:** Authenticate users before allowing them to perform state changes. Implement authorization policies to restrict access to sensitive states. * **Don't Do This:** Allow unauthorized users to modify the application state. Hard-code credentials or authorization policies. **Why:** Access control is critical to ensuring that only authorized users can modify the system's state. ## 7. Performance Optimization ### 7.1. Minimize State Updates **Standard:** Update the state only when necessary to avoid unnecessary re-renders or recalculations. * **Do This:** Batch state updates where appropriate to consolidate changes. Use memoization techniques to cache results of expensive calculations that depend on state. * **Don't Do This:** Update the state too frequently, leading to performance bottlenecks. **Why:** Reducing the number of state updates improves the application's responsiveness and reduces resource consumption. ### 7.2. Lazy Evaluation **Standard:** Use lazy evaluation ("Lazy<'T>") for compute-intensive state values that might not be needed immediately. * **Do This:** Defer calculations until the value is actually needed. * **Don't Do This:** Eagerly compute all state values, even if they are not immediately used. **Why:** Lazy evaluation can improve startup time and reduce memory consumption. ### 7.3. Structural Sharing **Standard:** When updating immutable state, leverage structural sharing to minimize memory allocation. * **Do This:** Utilize the "with" keyword for creating new copies of records with only the modified fields changed. This reuses the existing data where possible. * **Don't Do This:** Unnecessarily copy entire data structures when only a small part of the data is changed. **Why:** Structural sharing reduces memory allocations and improves performance when working with immutable data. These guidelines should provide a baseline for F# state management and serve as a reference point to ensure best practices followed are current, safe and efficient.