I get the desire to skip documenting, it’s not the fun part, and besides the code is self documented… right?
Look, I’m inherently lazy. Which means I don’t want to figure out how this works in a years time when I need to tweak it, or reinvent the wheel when I want to do something similar again. This is why I use OneNote to keep my own Knowledge Base for any task I do at work, and why I over document all my code.
Tip One: Seperate Sections
Use a Standard Sectioning to allow you to move around the code – and make those comments really distinct so it doesn’t get blurred into the code:
# Created by Works4me.info
#############--------------------------------------------------#
############# # All the Global variables that you will
############# +-+-+-+-+-+-+-+-+-+ # call in the rest of the code.
############# |V|a|r|i|a|b|l|e|s| #
############# +-+-+-+-+-+-+-+-+-+ # Sometime this might execute stuff, so
############# # think of this as a setup section too.
#############--------------------------------------------------# --------------------------------------
$global:Today = Get-Date
$global:AddDescription = $True
#VERSION OUTPUT DATA
$global:Version = "2.0"
$global:VersionDate = "1/2/2025"
#############--------------------------------------------------#
############# # The Functions that are repeatedly used
############# +-+-+-+-+-+-+-+-+-+-+-+-+-+-+ # by rest of the code, think of these
############# |C|o|r|e| |F|u|n|c|t|i|o|n|s| # as Functions used by Functions.
############# +-+-+-+-+-+-+-+-+-+-+-+-+-+-+ # --------------------------------------
############# #
#############--------------------------------------------------#
#---------------------------------------------------------------------------------------------
# Base Menu
#---------------------------------------------------------------------------------------------
function Make-Menu {
# This is a really big function
# and could distract from the point
# if it's in here.
}
#############--------------------------------------------------#
############# # The Various unique Functions
############# +-+-+-+-+-+-+-+-+-+-+-+-+ # that do the fancy pants part
############# |D|o| |F|u|n|c|t|i|o|n|s| # and navigation of your code.
############# +-+-+-+-+-+-+-+-+-+-+-+-+ # ----------------------------
############# #
#############--------------------------------------------------#
#---------------------------------------------------------------------------------------------
# Welcome Menu calling
#---------------------------------------------------------------------------------------------
function Do-Welcome {
cls
Make-Menu -OptionQuit -MenuTitle "WELCOME Menu" `
-Option1 "Display User" -Function1 "Do-Main01" `
-Option2 "Display Day" -Function2 "Do-Main02" `
-Option3 "Other Options" -Function3 "Do-SubMenu"
}
#############--------------------------------------------------#
############# # Simply the section in which
############# +-+-+-+-+-+-+-+-+-+-+-+ # you call all the functions &
############# |R|u|n| |S|e|c|t|i|o|n| # excute the core part of the
############# +-+-+-+-+-+-+-+-+-+-+-+ # code.
############# # ----------------------------
#############--------------------------------------------------#
#### Load the initial Menu
Do-Welcome
#---------------------------------------------------------------------------------------------When you look at the above code you see the skeleton of every PowerShell Script I write. Big block section markers, and banners for every individual Function.
- Variables
- Core Functions
- Do Functions
- Run Section
Tip Two: Side Notes
# Take action based on user input
switch ($choice01) {
1 {
if($Option1 -ne ""){ #--------------------------------------
cls # Note: Every choice will end the Menu
$test = & $Function1.ToString() # by setting $Choice01 to "Q".
$choice01="Q" # This means wherever you go, you
} # need to Call this Function again.
} #--------------------------------------
2 {
if($Option2 -ne ""){
cls
$test = & $Function2.ToString()
$choice01="Q"
}
}It might be annoying to add, but Notes like this stand out and are easy to read and spot when you are reviewing the code later.
Pro Tip: If you use Notepad++, you can hold ‘ALT’ and select any section to insert a column of comment characters.
Tip Three: Use Ascii Art to build those funky sections
I don’t have the time or inclination to manually create those Sections, so reuse what you can and build that template with an online Ascii Art generator like https://it-tools.tech/ascii-text-drawer
Tip Four: Explain Everything
#Check for Group Membership for each ($Group in $global:Groups.Groups) {
# Group does not exist in AD
if ($ADGroups.SamAccountName -notcontains $Group) {
Write-Host " $Group group does not exist in AD" -ForegroundColor Red
Continue
}
# User is already a member of the group
if ($ExistingGroups.SamAccountName -eq $Group) {
Write-Host " $UserSam already exists in group $Group" -ForeGroundColor Yellow
} else { # Add user to to group
Add-ADGroupMember -Identity $Group -Members $UserSam
Write-Host " Added $UserSam to $Group" -ForeGroundColor Green
}
}The code might be self explanatory, but with the comments it allow you to decipher the intention without having to interpret all of the code. This will means you can find the section you want to review or understand quickly.
Notice how I’ve attempted to blend the comment into the code, you could for example read:
“User is already a member of the group if SamAccount name equals $Group”
“Else add the user to the group”
Why this Matters
Future you will thank present you for these extra 10 minutes of documentation. When you’re troubleshooting at 2 AM or your colleague needs to modify your script, those comments become the difference between ‘genius!‘ and ‘what was I thinking?‘