Enhance your PowerShell Scripts: Tips for Writing Clean and Efficient Code

In the world of IT, scripts are not just useful tools; they are extensions of our professionalism. A well-designed script not only functions correctly but is also readable, maintainable, and scalable. In this article, I will explore the best practices for writing PowerShell scripts that are clean, efficient, and easy to maintain.

1. The Importance of Comments

Comments are essential for understanding the purpose and logic behind a script. Even the best code needs context.

Good practices for comments:

• Explain why you do something, not just what the code does.
• Use comments to describe complex parts or less obvious shortcuts.
• Keep comments up-to-date if you change the code.

Example of a clear comment:

# Validate file is existing
if (-not (Test-Path $FilePath)) {
    Write-Error "The file is not existing: $FilePath"
    exit
}
        

Comments in block:

<#
This script generates a report in csv for the last 30 days
#>

        

2.Error Handling: Making Your Scripts Resilient

Proper error handling improves the reliability of your scripts and reduces interruptions.

• Using Try-Catch:

try {
    # Attempt to copy a file
    Copy-Item -Path "C:\Source\file.txt" -Destination "C:\Destination\" -ErrorAction Stop
} catch {
    Write-Error "An error occurred while copying the file: $_"
}        

• Input Validation: Ensure that inputs are valid before processing them.

if (-not $FilePath) {
    Write-Error "The FilePath parameter is required."
    exit
}        

3. Modularize Your Code: Reusability and Organization

Dividing long scripts into functions and modules not only improves organization but also facilitates reuse.

Write clear and specific functions:

function Get-UserLastLogin {
    param (
        [string]$Username
    )
    # Returns the user's last login date
    Get-ADUser -Identity $Username -Properties LastLogonDate | Select-Object LastLogonDate
}        

Grouping functions into modules:

1. Create a .psm1 file with your functions.
2. Import the module with Import-Module. -> I explained this in another article: https://www.dhirubhai.net/pulse/los-m%C3%B3dulos-en-powershell-crear-e-importar-un-m%C3%B3dulo-jaume-valls-bota-qgx8f/

# File: MyModule.psm1
function Say-Hello {
    Write-Output "Hello, world!"
}        

4. Consistent Formatting and Style

Proper formatting makes code easier to read and maintain.

Use clear conventions:

• Descriptive names: $UserList instead of $u.
• CamelCase for variables ($UserName) and verb-noun for functions (Get-UserList).
• Consistent indentation (spaces or tabs, but never both).

Recommended tool: Use PSScriptAnalyzer to review your code.

Invoke-ScriptAnalyzer -Path .\MyScript.ps1        

5. Documentation in the Script

PowerShell allows you to document your scripts so that others (or yourself!) can easily understand them.

• Example of comments with Get-Help:

<#
.SYNOPSIS
Generates a report of active users in Active Directory.

.DESCRIPTION
This script searches for active users and generates a CSV file with the information.

.EXAMPLE
.\Get-ActiveUsers.ps1 -OutputPath C:\Reports\Users.csv
#>        

When you add these comments, Get-Help will display them:

Get-Help .\Get-ActiveUsers.ps1 -Full        

6. Testing and Debugging

Before deploying any script, test its functionality in a controlled environment.

Debugging: Use Write-Debug for optional messages that you can enable with -Debug.

Write-Debug "Starting parameter validation."        

Unit testing with Pester: Pester is a testing framework for PowerShell. -> I talked about this topic in these other articles:

• https://www.dhirubhai.net/pulse/pruebas-unitarias-en-powershell-introducci%C3%B3n-pester-parte-valls-bota-dbn0f/
• https://www.dhirubhai.net/pulse/pruebas-unitarias-en-powershell-introducci%C3%B3n-pester-parte-valls-bota-sccdf/

Describe "Test-Function" {
    It "Should return True when the input is valid" {
        (My-Function -Input 5) | Should -Be $true
    }
}        

Conclusion

A well-written script not only does the job but also saves time, avoids problems, and demonstrates professionalism. Follow these practices to take your PowerShell scripts to the next level.

Do you have any other tips or tricks? Share them in the comments and let's keep learning together!