Sharepoint-Toolbox/.planning/codebase/CONVENTIONS.md

Coding Conventions

Analysis Date: 2026-04-02

Naming Patterns

Functions:

• PascalCase for public functions: Write-Log, Get-ProfilesFilePath, Load-Profiles, Save-Profiles, Show-InputDialog
• Verb-Noun format using standard PowerShell verbs: Get-, Load-, Save-, Show-, Export-, Apply-, Validate-, Merge-, Refresh-, Switch-
• Private/internal functions prefixed with underscore: _Pkl-FormatMB, _Pkl-Sort, _Pkl-Repopulate, _Tpl-Repopulate, _Tpl-Log
• Descriptive names reflecting operation scope: Get-SiteStorageMetrics, Collect-FolderStorage, Collect-WebStorage, Export-PermissionsToHTML

Variables:

• camelCase for local variables: $message, $color, $data, $index, $siteSrl
• PascalCase for control variables and form elements: $form, $LogBox, $ClientId, $SiteURL
• Prefixed script-scope variables with $script: for shared state: $script:LogBox, $script:Profiles, $script:SelectedSites, $script:_pkl, $script:_tpl
• Abbreviated but meaningful names in tight loops: $s (site), $e (event), $i (index), $m (message), $c (color)
• Hashtable keys use camelCase: @{ name = "...", clientId = "...", tenantUrl = "..." }

Parameters:

• Type hints included in function signatures: [string]$Message, [array]$Data, [switch]$IncludeSubsites, [int]$CurrentDepth
• Optional parameters use = $null or = $false defaults: [string]$Color = "LightGreen", [System.Windows.Forms.Form]$Owner = $null
• Single-letter abbreviated parameters in nested functions: param($s, $e) for event handlers

File/Directory Names:

• Single main script file: Sharepoint_ToolBox.ps1
• Settings/profile files: Sharepoint_Settings.json, Sharepoint_Export_profiles.json, Sharepoint_Templates.json
• Generated report files use pattern: {ReportType}_{site/date}_{timestamp}.{csv|html}

Code Style

Formatting:

• No explicit formatter configured
• Indentation: 4 spaces (PowerShell default)
• Line length: practical limit around 120 characters (some HTML generation lines exceed this)
• Braces on same line for blocks: function Name { ... }, if ($condition) { ... }
• Region markers used for file organization: #region ===== Section Name ===== and #endregion

Regions Organization (in Sharepoint_ToolBox.ps1):

• Shared Helpers (utility functions)
• Profile Management (profile CRUD, loading/saving)
• Settings (configuration handling)
• Site Picker (dialog and list management)
• Template Management (capture, apply, storage)
• HTML Export: Permissions and Storage (report generation)
• PnP: Permissions and Storage Metrics (SharePoint API operations)
• File Search (advanced file search functionality)
• Transfer (file/folder transfer operations)
• Bulk Site Creation (site creation from templates)
• Internationalization (multi-language support)
• GUI (main form and controls definition)
• Event Handlers (button clicks, selections, menu actions)
• Structure (folder tree CSV parsing)

Comments:

• Inline comments explain non-obvious logic: # Groups rows that share the same Users + Permissions
• Block comments precede major sections: # -- Top bar --, # -- Site list (ListView with columns) --
• Section separators use dashes: # ── Profile Management ─────────────────────────────────
• Descriptive comments in complex functions explain algorithm: # Recursively collects subfolders up to $MaxDepth levels deep
• No JSDoc/TSDoc style - pure text comments

Import Organization

Module Imports:

• Add-Type -AssemblyName for .NET assemblies at script start:
  • System.Windows.Forms for UI controls
  • System.Drawing for colors and fonts
• Import-Module PnP.PowerShell dynamically when needed in background runspace blocks
• No explicit order beyond UI assemblies first

Error Handling

Patterns:

• Broad try-catch blocks with minimal logging: try { ... } catch {}
• Silent error suppression common: empty catch blocks swallow exceptions
• Explicit error capture in key operations: catch { $Sync.Error = $_.Exception.Message }
• Error logging via Write-Log with color coding:
  • Red for critical failures: Write-Log "Erreur: $message" "Red"
  • Yellow for informational messages: Write-Log "Processing..." "Yellow"
  • DarkGray for skipped items: Write-Log "Skipped: $reason" "DarkGray"
• Exception messages extracted and logged: $_.Exception.Message
• Validation checks return boolean: if ([string]::IsNullOrWhiteSpace(...)) { return $false }

Logging

Framework: Native Write-Log function + UI RichTextBox display

Patterns:

function Write-Log {
    param([string]$Message, [string]$Color = "LightGreen")
    if ($script:LogBox -and !$script:LogBox.IsDisposed) {
        # Append to UI with timestamp and color
        $script:LogBox.AppendText("$(Get-Date -Format 'HH:mm:ss') - $Message`n")
    }
    Write-Host $Message  # Also output to console
}

Logging locations:

• Long-running operations log to RichTextBox in real-time via background runspace queue
• Background functions use custom BgLog helper that queues messages: function BgLog([string]$m, [string]$c="LightGreen")
• Colors indicate message type: LightGreen (success), Yellow (info), Cyan (detail), DarkGray (skip), Red (error)
• Timestamps added automatically: HH:mm:ss format

Validation

Input Validation:

• Null/whitespace checks: [string]::IsNullOrWhiteSpace($variable)
• Array/collection size checks: $array.Count -gt 0, $items -and $items.Count -gt 0
• Index bounds validation: if ($idx -lt 0 -or $idx -ge $array.Count) { return }
• UI MessageBox dialogs for user-facing errors: [System.Windows.Forms.MessageBox]::Show(...)
• Function-level validation via Validate-Inputs pattern

String Handling

HTML Escaping:

• Custom EscHtml function escapes special characters for HTML generation:

  function EscHtml([string]$s) {
      return $s -replace '&','&amp;' -replace '<','&lt;' -replace '>','&gt;' -replace '"','&quot;'
  }
  

• Applied to all user-supplied data rendered in HTML reports

String Interpolation:

• Double-quoted strings with $variable expansion: "URL: $url"
• Format operator for complex strings: "Template '{0}' saved" -f $name
• Localization helper function T for i18n strings: T "profile", T "btn.save"

Function Design

Size: Functions range from 5-50 lines for utilities, 100+ lines for complex operations

Parameters:

• Explicit type declarations required
• Optional parameters use default values
• Switch parameters for boolean flags: [switch]$IncludeSubsites
• Complex objects passed as reference (arrays, hashtables)

Return Values:

• Functions return results or arrays: return @(), return $data
• Boolean results for validation: return $true / return $false
• PSCustomObject for structured data: [PSCustomObject]@{ Name = ...; Value = ... }
• Void operations often silent or logged

Object/Struct Patterns

PSCustomObject for Data:

[PSCustomObject]@{
    name              = "value"
    clientId          = "value"
    capturedAt        = (Get-Date -Format 'dd/MM/yyyy HH:mm')
    options           = @{ structure = $true; permissions = $true }
}

Hashtable for Mutable State:

$script:_pkl = @{
    AllSites      = @()
    CheckedUrls   = [System.Collections.Generic.HashSet[string]]::new()
    SortCol       = 0
    SortAsc       = $true
}

Synchronized Hashtable for Thread-Safe State:

$sync = [hashtable]::Synchronized(@{
    Done  = $false
    Error = $null
    Queue = [System.Collections.Generic.Queue[object]]::new()
})

Class/Type Usage

• Minimal custom classes; primarily uses [PSCustomObject]
• Extensive use of .NET types:
  • [System.Windows.Forms.*] for UI controls
  • [System.Drawing.Color] for colors
  • [System.Drawing.Font] for typography
  • [System.Drawing.Point], [System.Drawing.Size] for positioning
  • [System.Collections.Generic.HashSet[string]] for efficient lookups
  • [System.Collections.Generic.Queue[object]] for message queues
  • [System.Management.Automation.Runspaces.*] for background execution

Date/Time Formatting

Consistent format: dd/MM/yyyy HH:mm (European format)

• Used for timestamps in reports and logs
• Timestamps in logs: HH:mm:ss
• Storage/file metrics: dd/MM/yyyy HH:mm

Performance Patterns

Batch Operations:

• Form updates wrapped in BeginUpdate() / EndUpdate() to prevent flickering
• ListView population optimized: clear, populate, sort in batch

Threading:

• Long-running PnP operations execute in separate runspace
• Main UI thread communicates via synchronized hashtable + timer polling
• Async UI updates via Timer with DoEvents() for responsiveness

---

Convention analysis: 2026-04-02