The single most important step that can be taken with regard to Coding Standards in any corporate environment is for the developers, managers and stakeholders to agree that they should at least have some.  This decision does not need to be a catalyst for the bureaucrats who have never watched the clock tick past 01:00hrs, whilst sifting through a stack trace, trying to weed out a inexplicable access violation, to author an unwieldy tome that doesn't actually improve the development life cycle.

Rather, coding standards should be succinct, achievable and universally understood.  By understood, I mean the understanding of why they exist, as opposed to just understanding that thou shall or thou shalt.  Understanding the reasoning behind a particular standard allows all involved to support or challenge its intent as programming languages and frameworks evolve in the environment.

Many software engineers talk about the "ilities" when describing good coding practices.  The concepts that they are talking about include:

There's good reason why "popular" novels in your local book store are in fact popular.  Reading such books isn't a chore; their structure, language and content conjures up imagery that draws you in, with the actual text seeming to disappear as you read.  These are well written books.   This is in contrast to some texts where every third page has to be read at least twice before making even partial sense.

This experience is analogous to well-written programming code.  Having to read a piece of code when expanding on its original functional specification or attempting to identify a bug shouldn't be [too much of] a chore.   Its stucture, layout and semantics should make it possible for its purpose to be clear - as with the novel, the code itself (the text) should disappear as you read.

Regardess of the chosen programming languages and frameworks, software development ultimately results in human beings mapping out problems, through various abstractions into programming code.  This code then needs to be maintained, and it is here that the true cost of software development becomes apparent.  In order for any sizeable piece of software to be effectively maintained in a team environment, the code base must be readable.

The sections below offer a number of guidelines that should help in making code more maintainable.

The problems addressed by software can sometimes be very complex in nature, and it is up to the software developer to break these problems into logical chunks and abstractions, and then map them into programming code.  

Structuring code into modules, classes, functions and procedures allows the developer to divide the problem into understandable units of behaviour.  Doing so makes it easier for future onlookers to make the congnitive leap between code and purpose.

Well stuctured code also makes it possible to hide complexity and also encourages code re-use.

Gone are the days where many hours had to be spent optimising assembly language routines to eke out two or three more clock cycles (ever written an Interrupt Service Routine, or ISR, that must complete during the "vertical blank" of a raster-based screen refresh... anyone?).  My point being that we no longer need to over-optimise code to the extent that it's impossible to decipher (even by the original developer, some months on).  Sure, if a particular piece of code is going to be executed many hundreds of thousands of times, then look out for potential optimisations, but focus your efforts accordingly.

In short, don't try to be too clever, and, instead, think about the next person who may have to make sense of your code.  If the only solution to a given problem involves a particularly complicated bit of code, encapsulate the code in a function and supplement the function with plenty of meaningful .

Lynne Truss' famous book, "Eats Shoots and Leaves" demonstrates how punctuation can change the meaning of a piece of writing.   If we think of the syntax of a programming language as being its grammar, then the equivalent of punctuation (a tool for conveying meaning) can be thought of in terms of code layout, naming conventions and comments.

We'll cover separately below, but for now:

• Indent your code.  No, really, please indent your code.  Code indendation is to a computer program listing what a conductor is to an orchestra.  It doesn't matter what indentation scheme you use, just use one.
• Give your functions, procedures and class methods purposeful names.  Take a lead from Jeffrey Snover and his team and include a verb/noun phrase if possible, e.g.: calculateTax() instead of just tax().
• For functions that return either true or false, use names like accountIsInCredit().  This makes calls to this function read more naturally, for example: if ( accountIsInCredit( ... ) ) { ... }
• Give all variables proper names; if you're declaring a variable, it has a purpose.  That is, avoid names like temp, tax1, Etc.
• For languages such as PowerShell, that will often be edited without an IDE, seriously consider using (see below) for variable names.
• When creating classes or tables, make the class or table name singular (e.g.: employee).  Then, when defining class properties or column names, do not include the class name, e.g.: employee.id, rather than employee.employeeID.
• Use the built-in hardening features of the language to make your code more robust, e.g.: , and .

Keeping with art-based analogies, comments are to programming code what stage direction is to a theatre production.  You can perform a play in the absence of the playwright's direction, but it won't necessarily convey the same meaning.   The very language of programming code shows us how something is done, but it doesn't necessarily tell us why.

Comments should be used to:

• If it's not obvious, explain the purpose of sections of code;
• Explain why a particular path has been chosen (i.e.: explain what isn't in the code, and why); and
• On the rare occasions, explain how a piece of code works (only if the code can't be refactored).

Long story short, comments are there to add value.  Think back to the stage direction analogy; why did the playright state that the next line should be whispered, rather than shouted?  If the words themselves don't make things clear, add direction.  Finally, keep things brief and to the point, otherwise TL;DR syndrone will prevail.

When developing PowerShell scripts, try to avoid referencing global or script variables (see ) directly from within functions and procedures.  Instead, pass values to your functions and procedures as normal parameters or as references.

The exceptions to this guideline are when referencing global variables or when referencing script variables that are defined and referenced within the same .   The rationale behind this guideline is that direct references to global or script variables inhibit code re-use, that is, a function or procedure can't just be "lifted"; the "liftee" must be aware of all variable dependencies.

Okay, before we start, I fully accept that "system" Hungarian Notation is not appropriate for fully-fledged applications development, where Object Orientated languages, such as Microsoft C#, and Integrated Development Environments (IDEs), such as Microsoft Visual Studio, are used to develop potentially dozens of classes in order to model a given problem domain.

However, the majority of PowerShell code that I come across resides in the shadowy worlds of the systems administrators who keep the servers alive and the systems integrators, who develop numerous server-side interface scripts to get various heterogeneous systems to "gel" into a single cohesive entity.

It's in this world that things are generally done a little differently.  For one thing, the toolsets are often different; the likes of Microsoft Visual Studio are replaced by tools such as , Notepad++ and TextPad.   This means that development of PowerShell scripts has to be done with far less automated assistance (code completion, data type checking, Etc.).   It is therefore far more difficult for the developer to quickly see that a given variable is, say, a 32-bit signed Integer, a character array, or an instance of a StringBuilder class, Etc.  In circumstances like this, "system" Hungarian Notation does actually help massively.

That's the preamble out of the way.  In essence, "system" Hungarian Notation involves prefixing variable names with a short mnemonic that identifies the data type assignment for the given variable, for example strUserName, longSessionId or boolConnected.   Again, in the absence of proper development IDEs, these mnemonics make the job of code development just a little bit easier.

At the time of writing, PowerShell has over 150 built-in .   I would strongly encourage that you limit the use of aliases to command-line interaction only.  In this environment, brevity improves your efficiency and others aren't necessarily expected to understand what you are doing.   This is in contrast to writing scripts, publishing code to online repositories or posting solutions to technical forums, where aliases only serve to confuse those that aren't as familiar with PowerShell as yourself.

Worse still is the use of custom aliases (ones created by yourself).  These should never be used in any form of script artifact, as you cannot guarantee their existence in other environments and you cannot guarantee that anyone else will understand their meaning.

In short, the use of aliases can severely impact a number of the described above and are therefore best avoided.