docs: map existing codebase
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
210
.planning/codebase/CONVENTIONS.md
Normal file
210
.planning/codebase/CONVENTIONS.md
Normal file
@@ -0,0 +1,210 @@
|
||||
# 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:**
|
||||
```powershell
|
||||
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:
|
||||
```powershell
|
||||
function EscHtml([string]$s) {
|
||||
return $s -replace '&','&' -replace '<','<' -replace '>','>' -replace '"','"'
|
||||
}
|
||||
```
|
||||
- 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:**
|
||||
```powershell
|
||||
[PSCustomObject]@{
|
||||
name = "value"
|
||||
clientId = "value"
|
||||
capturedAt = (Get-Date -Format 'dd/MM/yyyy HH:mm')
|
||||
options = @{ structure = $true; permissions = $true }
|
||||
}
|
||||
```
|
||||
|
||||
**Hashtable for Mutable State:**
|
||||
```powershell
|
||||
$script:_pkl = @{
|
||||
AllSites = @()
|
||||
CheckedUrls = [System.Collections.Generic.HashSet[string]]::new()
|
||||
SortCol = 0
|
||||
SortAsc = $true
|
||||
}
|
||||
```
|
||||
|
||||
**Synchronized Hashtable for Thread-Safe State:**
|
||||
```powershell
|
||||
$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*
|
||||
Reference in New Issue
Block a user