FredBainbridge

10 Things You Need As An Enterpise Scripter

#3 Standards

Having strictly adhered to standards allows for a faster onboarding process for new team members. Following standards is also very helpful for the times when other team members have to iterate on and improve an existing solution. There is already enough to think about when doing automation planning and coding work. Having well defined coding and documentation standards eliminates a lot of wasted time and energy having to sort through inconsistencies or locate missing artifacts. As you create solutions you should always be acutely aware that someone else may have to work with your code someday and one of your goals should always be to make sure it as easy as possible for the next person to be able to quickly digest your code and be able to get to work on the next iteration in as little time as possible. Without strictly adhered to standards this becomes very difficult.
https://twitter.com/JeffHicks/status/906966816857235457

Code Formatting

You need consistency in your scripts. Do you code like this?

Foreach($beer in $beers) {
}

Or like this

Foreach($beer in $beers)
{
}

Pick one and stick to it. Tabs or spaces? Regardless, be consistent! The motivating factor behind code formatting is ability to be able to quickly look at code and understand what it is trying to accomplish. Avoid using overly complicated long lines of code. Don’t be afraid to break something up over a few lines especially if it makes it easier to read. But never use a backtick (`) character, it is evil! Remember, when someone else comes to look at this code in 6 months you want to make sure that individual doesn’t have to spend a month getting up to speed on what the code is actually doing. You want to reduce the complexity and increase the “human readability” of your code whenever possible by using strict formatting standards.

VSCode Tip Version 1.4.0 of the PowerShell extension for VS Code allows the formatting presets for the most common code style conventions. (OTBS, Stroustrup, Allman) to help format your code quickly.
Put the following line your User Settings (shortcut key, ctrl + ,)

"powershell.codeFormatting.preset":"Stroustrup"

PowerShell Functions You cannot over utilize functions with PowerShell. If you ever have repeatable code or a branch of logic that gets a little hairy be sure to wrap it up in a function. This has two major benefits. First it improves the human readability of you code and second the more code you wrap in functions the easier it is to unit test your code using Pester.

Documentation

What makes for good documentation when it comes to scripting? This is a debate as old as the For loop. In my opinion good documentation means that you have examples for how to use the script for the use cases it was designed for and this documentation is easy to find in a consistent and logical location. For added value you also want to highlight the different ways the automation you have created can be consumed or called upon. i.e. If a script or web API has any number of parameters, what do they all do? Why? Show some examples.

Documentating your PowerShell Use the built in Comment Based Help! PowerShell does an amazing job of providing a means for you to document your script within the script file itself. If you spend the time making sure each available section of documentation is filled out for each function and all parameters, this alone in most cases should be all the documentation you need. The entire PowerShell help engine is dynamic, if you put all your notes in properly formatted sections of your script then PowerShell will recognize these and make it available to anyone who asks. i.e.

Get-Help -Name New-fbCustomWidget

This little cmdlet will show your custom help that you embedded in the script using Comment Based Help. This is very cool and incredibly useful! Example

A Note on VSCode There is a reason Tooling was the very first item in this list. Choosing the proper tooling can early can pay dividends later. For example, VS Code can scaffold Comment Based Help for functions automatically based on existing parameters. Small things like this can go a long way to not only adhering to standards but can also really reduce the amount of key strokes needed for excellent documentation.

VS Code Function Help

Don Jones wrote an article many years ago called Build a Better Function. It has a complete shell of a function with with all the comment based help available in it. It is simple outstanding and I reference it at least quarterly.

Use PS Script Analyzer rules to enforce some of your coding standards. An example I am big fan of is prefixing any custom function or cmdlets with something that identifies it as being written in house. i.e New-fbCustomWidget. You can create a custom rule to alert when a custom defined function doesn’t have your predefined prefix designator. Having a prefix for custom functions is very useful for identifying when something homegrown is being called instead of something out of the box or 3rd party.

A non-complete example set of coding standards
- Script location and file name
- Passes all script analyzer rules
- Has existing markdown documentation
- Has pester tests
- Passes pester tests
- Has full function documentation for all parameters and use cases

Enforcing Standards via Automation
Use all the tools available to you to automatically enforce your agreed upon standards. Ideally this means using some form of continuous integration (The 5th thing you need as an Enterprise level scripter) to check that there no PS Script Analyzer Rules violations, all documentation exists in the correct spots, all peer reviews are completed, all unit and integration tests exist, proper change control has been adhered to and all other artifacts identified exist in their proper locations. There are even tools out there to automatically format and beautify any code checked in. If any of these tests fails, reject the code and send it back for further refinement with a nicely formatted list of suggested improvements.

Stay tuned for more!


Share