Turn "It Works, But Don't Touch It" into Code Any Admin Can Safely Change — Behavior-Preserving PowerShell Refactoring

The workflow should follow several core principles.

The default objective is to improve structure without changing what the script does.

Any behavioral change must be:

• Explicitly identified
• Separately documented
• Justified
• Approved before implementation

PowerShell supports concise syntax, aliases, script blocks, pipelines, and advanced language features. These can be useful, but brevity is not always readability.

The refactored script should be understandable to another qualified administrator without requiring them to decode unnecessarily compact expressions.

Avoid rewriting the entire script simply because a different design is possible.

Prefer incremental changes that:

• Improve clarity
• Reduce risk
• Preserve familiar behavior
• Can be reviewed easily
• Can be tested independently

A function should generally have one clearly defined responsibility.

For example, a single function should not simultaneously:

• Query Active Directory
• Transform records
• Write a CSV
• Send an email
• Delete temporary files
• Update a ticket

Those activities should usually be separated into smaller functions coordinated by a clear execution flow.

$path = "C:\Reports"
$users = Get-ADUser -Filter * -Properties Enabled, LastLogonDate
$disabled = @()
foreach ($u in $users) {
    if ($u.Enabled -eq $false) {
        $disabled += $u
    }
}
$disabled |
Select SamAccountName, LastLogonDate |
Export-Csv "$path\disabled.csv" -NoTypeInformation
Write-Host "Done"

Intended behavior:

• Retrieve all Active Directory users
• Select disabled users
• Export their account names and last logon dates
• Save the report as disabled.csv
• Display a completion message

The script is short and understandable, but it contains several maintainability concerns:

1. The report path is hardcoded.
2. The variable $u is not descriptive.
3. The array addition operator += can perform poorly with large collections.
4. The script retrieves all users and filters them locally even though Active Directory can perform the filtering.
5. Select uses an alias instead of the full Select-Object cmdlet.
6. The output filename is constructed with string interpolation instead of Join-Path.
7. The script does not validate that the destination folder exists.
8. Write-Host is acceptable for an interactive message but is difficult to consume programmatically.
9. The script executes immediately and cannot easily be imported or tested.
10. The export logic is not encapsulated in a reusable function.

Changing the Active Directory query from -Filter * to a server-side disabled-account filter improves efficiency but could potentially alter behavior if the existing local filtering has undocumented assumptions. That change should therefore be identified separately from a strictly behavior-preserving refactor.

function Export-DisabledAdUserReport {
    <#
    .SYNOPSIS
    Exports a report of disabled Active Directory users.
    .DESCRIPTION
    Retrieves Active Directory users, selects disabled accounts, and exports
    the account name and last logon date to a CSV file.
    .PARAMETER OutputDirectory
    Directory where the disabled-user report will be saved.
    .PARAMETER FileName
    Name of the generated CSV file.
    .EXAMPLE
    Export-DisabledAdUserReport -OutputDirectory 'C:\Reports'
    .OUTPUTS
    System.IO.FileInfo
    #>
    [CmdletBinding()]
    [OutputType([System.IO.FileInfo])]
    param(
        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string]$OutputDirectory,
        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [string]$FileName = 'disabled.csv'
    )
    if (-not (Test-Path -LiteralPath $OutputDirectory -PathType Container)) {
        throw "The output directory does not exist: $OutputDirectory"
    }
    $outputPath = Join-Path -Path $OutputDirectory -ChildPath $FileName
    $allUsers = Get-ADUser -Filter * -Properties Enabled, LastLogonDate
    $disabledUsers = $allUsers |
        Where-Object { $_.Enabled -eq $false } |
        Select-Object -Property SamAccountName, LastLogonDate
    $disabledUsers |
        Export-Csv -LiteralPath $outputPath -NoTypeInformation
    Write-Verbose "Disabled-user report exported to $outputPath"
    Get-Item -LiteralPath $outputPath
}

The refactor preserves the original user-filtering approach by retaining Get-ADUser -Filter * followed by local filtering.

A separate optimization could replace it with:

Get-ADUser -Filter 'Enabled -eq $false' -Properties LastLogonDate

That change may improve performance but should be tested independently because it changes where filtering occurs.

A full rewrite can introduce new defects and remove undocumented behavior.

Prefer smaller, reviewable changes unless the original structure is fundamentally unusable.

A refactor may appear equivalent while changing:

• Pipeline enumeration
• Error propagation
• Null handling
• Output types
• Sorting
• Object property order
• Date conversion
• Encoding
• Case sensitivity
• Remote execution context

Behavior should be tested, not assumed.

Shorter code is not necessarily clearer code.

Avoid compressing logic into dense one-liners simply to reduce line count.

Function extraction can become excessive.

A helper function should usually represent:

• A distinct responsibility
• Reusable behavior
• A testable unit
• A meaningful abstraction

Creating a separate function for every two or three lines can make execution flow harder to follow.

Renaming functions, parameters, or public commands can break:

• Scheduled tasks
• Other scripts
• Documentation
• Pipeline jobs
• Module consumers
• Monitoring rules

Public interfaces require compatibility planning.

A readability refactor is not the time to add:

• Email alerts
• New export formats
• Parallel execution
• Database storage
• New modules
• New configuration systems
• Additional parameters unrelated to the objective

Keep scope controlled.

AI-generated comments may sound plausible while misunderstanding the business logic.

Every comment should be reviewed for accuracy.

Static analysis rules are valuable, but not every warning requires the same response.

Document justified exceptions rather than making changes that reduce clarity or compatibility.