Powershell Script DIY:Naming Conventions

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