Table of Contents
Engineering Practices
Summary
PowerShell Engineering Practices define shared rules, behaviors, and guidance for writing scripts that are easy to read, review, and support over time.
Developing code as a team introduces challenges beyond individual work, especially around personal preferences. Establishing common practices improves consistency, quality, and efficiency, and enables more effective code reviews by setting clear expectations.
These practices fall into two categories: Style Guide and Best Practices.
Concepts
Style Guide
A Style Guide defines how code looks and is structured. Its goal is consistency and readability through a uniform appearance and predictable flow. Style guides focus on observable, surface-level characteristics that make code easier to scan, review, and maintain.
Common areas covered by a style guide include formatting (indentation, spacing, line length), naming conventions, file and directory layout, comment and documentation format, and the ordering of imports or declarations.
Style Guide rules are objective and repeatable, making them enforceable through formatters and linters. Violations are typically mechanical issues rather than matters of judgment.
Prioritize writing code that is easy to read rather than easy to write. Scripts often live for years and are revisited infrequently, usually when something breaks or needs enhancement. At that point, the original author may not remember the context, and new contributors will have none. Readable code reduces this friction.
Linting
Linting is automated analysis that identifies issues before code runs and enforces style consistency. In PowerShell, linting can be performed from the command line or within VS Code.
Microsoft's PSScriptAnalyzer is the primary tool used for PowerShell linting. See PowerShell Lint for additional details. See PowerShell Lint for additional information. Linting is automated analysis that identifies issues before code runs and enforces style consistency. In PowerShell, linting can be performed from the command line or within VS Code.
Best Practices
Best Practices focus on how code behaves and how problems are approached. Unlike style rules, they are guidance rather than strict requirements and are not always enforceable automatically. For PowerShell, PoshCode provides a community-driven source of best practices.
Best Practices commonly address areas such as error handling, testing, performance, security, API and interface design, modularity and reuse, and deployment safety.
Consistency within a script or project is critical. Consistent structure and behavior improve readability, maintainability, and reliability. When maintaining existing scripts, align with the script's established style rather than introducing a new style in isolated sections. This minimizes cognitive overhead for future readers.
Practical
Tooling
Use available tooling to reinforce Engineering Practices. VS Code and PowerShell command-line tools provide features that automatically improve code quality and consistency. While this guide highlights VS Code, equivalent command-line tooling is available.
Enable automatic trimming of trailing whitespace by setting files.trimTrailingWhitespace to true in VS Code settings.
Enable automatic formatting on save by setting editor.formatOnSave to true.
Enable auto-save by setting files.autoSave to afterDelay if desired, keeping in mind the interaction with format-on-save behavior.
Note: If auto-save is set to afterDelay, formatOnSave only triggers on manual saves.