Powershell Script DIY: Naming
Conventions
Greetings and welcome to
“Help! I’m stuck in my Powershell!” Today we address an important
issue that plagues all Powershell scripter’s: The dreaded “I have 44 different
script files named some variation of "Foo.PS1!” A naming convention is a
documented system of naming files, variables, folders, ect. Naming
convention in a production environment is paramount as it helps reduce
confusion when you have multiple scripts you are working on. Here I
will help you with a Simple naming convention for a file, a folder, and a
script. But first, I will define what can, and cannot be used as an Object name
in windows:
File / folder
limitations & why they are in place:
|
/ and \
|
used for directory paths
|
|
? and *
|
Used as wildcards
|
|
< and >
|
Used for system functions
|
|
:
|
Used to define a port when
referencing a port location
|
|
|
|
Used to string commands together
|
|
“
|
Used to define a path or file that
contains spaces
|
|
Any name over 255 characters long
(Fat32) or 256 characters long (NTFS)
|
The maximum file name can only be
260 characters long, including extension.
|
|
Space at the end of a name
|
A space indicates a separation,
while allowed inside a name it creates system conflicts at the end
|
|
Period at the end of a name
|
A period indicates a separation
between the name and the extension
|
|
com1, com2, com3, com4, com5,
com6, com7, com8, com9, lpt1, lpt2, lpt3, lpt4, lpt5, lpt6, lpt7, lpt8, lpt9,
con, nul, and prn
|
Reserved by windows for system use
|
|
(Source:
http://support.grouplogic.com/?p=1607)
|
|
Now that we have defined
what you cannot do, let’s look at some of the things you can use in the naming
convention:
|
Purpose
|
Computer name
|
|
Date
|
Server name
|
|
Time
|
Physical location
|
|
Version number
|
Group Name
|
|
Author
|
Data Source
|
FILE Naming Conventions:
When creating a file
naming convention you must first define the intent of the file. Our purpose
is to house source data from our source “foo”:
Foosourcedata
I prefer to separate
portions of my name with either – or _:
Foosourcedata_
The source of our data
is Server1:
Foosourcedata_Server1_
I like to include the
date-time group:
Foosourcedata_Server1_01JAN2013_1200
And the important thing
to add at the end is the extension. An extension is not necessary
for Powershell to pull data; rather it is useful for debugging. I
prefer to use the *.log for source data:
Foosourcedata_Server1_01JAN2013_1200.log
So we used
“Intent_Source_Date_Time.extention” Remember, this is only an example, and you
do not need to follow this example to the letter.
Folder Naming
Conventions:
Folders are a slightly
different case as their purpous and function are fundamentally different. With
that being said, instead of starting with “intent,” we will start with
“contains.” Defining what your folder contains is important, as it
helps navigation to the files it contains. This example will use “Foo
source data files”:
Foo source data files
If this is a sub
directory, you can append the group, or variable that differentiates those
files contained within from the rest of the files:
Foo source data files_Server1
Additional items can be
added at the end, but remember that the folder name should generally describe
everything it contains.
Script Naming Conventions
As scripts are
inherently files, they can be treated as such when naming them, with a few
caveats: The file name should start with its purpose and not what it
contains, and you should always end it with a version number. To
start we will use fooscript to describe its purpose:
Fooscript
It is a good idea to
follow this with the author’s initials if you are working in a multi-admin
environment:
Fooscript_JRD
Instead of a date I
prefer using a version number (I will explain more on this later on in the
post):
Fooscript_JRD_1.0.1
If this is a work in
progress you can append “Working” after this, while it is not required, it is a
good idea if you work on a shared system, or the script resides on a network
drive:
Fooscript_JRD_1.0.1_Working
Finally, you should
append the extention particular to your scripting language. We use
Powershell here, so the extension is “*.PS1”:
Fooscript_JRD_1.0.1_Working.PS1
The version number is an
unofficial industry number that is delimited by periods used to identify the
progress of the script. Normally, there are 3 values:
1.2.3
The first number, “1”
indicates major changes. This should only change if there is an
major revision to the code. The second number, “2” refers to Incremental
change. This means an added minor feature, or changing out a block
of code for a more effective block without fundamentally altering the function
of the script. The final number, “3” indicates a bug fix, i.e. if
the script crashes under specific circumstances.
As always, I encourage
commenting & sharing. It does no one good if we keep knowledge and
resources to our self!
Sources:
http://support.grouplogic.com/?p=1607