Update TODO.md

- Change '.Net' to '.NET' to keep it consistent.
- Remove several spurious blank lines.
- Change 'PowerShell Classes' to 'PowerShell classes'.
- Change "'s" to "or".
- Change 'makes sense more sense' to 'makes more sense'.
- Move 'param()' in '[CmdletBinding()]param()' to the next line.
- Change 'comment based help' to 'comment-based help'.
- Change 'a about_ModuleName' to 'an about_ModuleName'.
- Change 'that pases parameters positionally' to 'that passes parameters positionally'.
- Change 'PsCmdlet.ThrowTerminatingError' to '$PSCmdlet.ThrowTerminatingError'.
- Change 'PsCmdlet.WriteError' to '$PSCmdlet.WriteError'.
- Change inconsistencies with the styling guide/conventions in the example code for function ThrowError:
   - Change typo 'errorrecord' to 'error record'.
   - Move brace after 'function ThrowError' to the same line.
   - Move parenthesis after 'param' to the same line.
   - Change 'parameter' to 'Parameter'.
   - Change '$exception = New-Object $ExceptionName $ExceptionMessage;' to '$exception = New-Object -TypeName $ExceptionName -ArgumentList $ExceptionMessage' (so using named parameters instead of positional parameters and removing the unnecessary semicolon at the end).
- Change 'Discuss: when is this critical (-whatif) and optional (-confirm_' to 'Discuss: when is this critical (-WhatIf) and optional (-Confirm)'.
- Change 'Discuss: when should you call PSCmdlet.ShouldProcess vs PSCmdlet.ShouldContinue (-Force)' to 'Discuss: when should you call $PSCmdlet.ShouldProcess vs $PSCmdlet.ShouldContinue (-Force)'.
- Change more inconsistencies in example code:
   - Remove unnecessary semicolons at the end of the line.
   - Add space after 'foreach'.
   - Remove inconsistent spacing.
   - Add space after 'if'.
- Change more small typos.

P.S.: Make '$errorRecord = New-Object System.Management.Automation.ErrorRecord $exception, $ErrorId, $ErrorCategory, $ExceptionObject' code that actually works! This code will generate the error **New-Object: Cannot bind argument to parameter 'TypeName' because it is null.**!

Author: richy58729

Best-Practices/TODO.md

@@ -1,6 +1,6 @@
 These documents are in an extremely rough state, not suitable for inclusion in the main guide yet.
 
-### Using The .Net Framework
+### Using the .NET Framework
 
 - [Control what gets exported in a module](#control-what-gets-exported-in-a-module)
     - [Specify when to use a Manifest for a module](#specify-when-to-use-a-manifest-for-a-module)
@@ -51,19 +51,17 @@ TODO
 #### Control what gets exported in a module
 #### Specify when to use a Manifest for a module
 
-
 #### Use RequiredAssemblies rather than Add-Type
 #### Use Add-Type rather than Reflection
 Avoid using `[System.Reflection]` to load assemblies when possible. Particularly avoid `LoadWithPartialName` (specify the full name instead).
 
 #### Use Add-Type for small classes or PInvoke calls
-TODO: Is this better than PowerShell Classes, for compatibility?
+TODO: Is this better than PowerShell classes, for compatibility?
 
 #### Prefer shipping binaries over large compilations
-With PowerShell 5, security is tighter, and compiling code in memory will be frowned upon. Now that we have PowerShellGet and the PowerShell Gallery, there are few reasons 's no reason to avoid binaries.
-
-TODO: Discuss: when does embedding C# code makes sense more sense than just compiling it every time?
+With PowerShell 5, security is tighter, and compiling code in memory will be frowned upon. Now that we have PowerShellGet and the PowerShell Gallery, there are few reasons or no reason to avoid binaries.
 
+TODO: Discuss: when does embedding C# code makes more sense than just compiling it every time?
 
 ### Performance
 
@@ -72,10 +70,10 @@ Prefer foreach(){} over ForEach-Object
 Prefer .foreach and .where over cmdlets
 Prefer functions with process blocks over ForEach-Object
 
-#### Know when to use .Net
-Prefer writing wrapper functions to just calling .Net APIs
+#### Know when to use .NET
+Prefer writing wrapper functions to just calling .NET APIs
 Discuss: System.IO file loading vs Get-Content (large files)
-Discuss: Other examples of .Net API calls that are clearly faster?
+Discuss: Other examples of .NET API calls that are clearly faster?
 Discuss: Casting for creating objects
 
 ### Error Handling
@@ -85,7 +83,6 @@ Discuss: Avoid depending on `$?` -- why?
 Discuss: Never use `$Error` in scripts (always use -ErrorVariable)
 Discuss: Interactively, always copy $Error[0] to $e or something
 
-
 ### General Design Principles
 
 #### Use custom objects
@@ -103,26 +100,24 @@ Discuss: During development, always write scripts, which are automatically re-pa
 This is in the Style Guide too, but we should discuss it in more depth here, and link to it from the Style Guide.  Scripts should start life as something like this:
 
 ```
-[CmdletBinding()]param()
+[CmdletBinding()]
+param()
 process{}
 end{}
 ```
 
 You can always ignore one of the blocks, and add parameters and such, but you should never write a script without CmdletBinding, and you should never write one without at least considering making it take pipeline input
 
-
 ### Include Help
 
 TODO: Link to StyleGuide about formatting help
-Discuss: Minimum acceptable comment based help: Synopsis, Parameters, and an example for each parameter set (plus pipeline examples if you can contrive one)
+Discuss: Minimum acceptable comment-based help: Synopsis, Parameters, and an example for each parameter set (plus pipeline examples if you can contrive one)
 Discuss: Benefits of MAML help files
 
-#### Always ship a about_ModuleName with modules
+#### Always ship an about_ModuleName with modules
 
 Discuss: Other reasons to write about_topics
 
-
-
 #### Prefer PipelineByPropertyName parameters.
 Discuss: This allows the most flexibility: piping objects and using scriptblocks to shape it for parameters. Unless you absolutely need to write a `begin` block and use this parameter in it, you probably should accept it on the pipeline.
 
@@ -137,7 +132,7 @@ You can use aliases to map parameters to property names of objects which might b
 Particularly when splatting PSBoundParameters to the next function, if that function isn't `[CmdletBinding()]` (it should be!) you must remember to strip the common parameters if they're present.
 
 #### Specify positional parameters, but don't use them
-When writing at the command line, positional parameters are a blessing, but they can be confusing for future readers. You should always expose your parameters positionally when it makes sense, but you should rarely share a script that pases parameters positionally.
+When writing at the command line, positional parameters are a blessing, but they can be confusing for future readers. You should always expose your parameters positionally when it makes sense, but you should rarely share a script that passes parameters positionally.
 
 #### Specify short aliases, but don't use them
 Again, for the sake of typing, it's particularly useful if you can provide two-letter aliases for each of your parameters such that every parameter has a two-letter or less name which is unique.
@@ -155,72 +150,69 @@ ValueFromPipelineByPropertyName = $true, HelpText = 'The name of the file to rea
 [String]$File
 ```
 
-
 #### Use PsCmdlet.ThrowTerminatingError rather than throw
 #### Use PsCmdlet.WriteError rather than Write-Error
 Discuss: These need example output to explain why they're better
 Discuss: a common template (from the Microsoft team) for throwing errors
 
 ```
-# Utility to throw an errorrecord
-function ThrowError
-{
-    param
-    (
-        [parameter(Mandatory = $true)]
+# Utility to throw an error record
+function ThrowError {
+    param(
+        [Parameter(Mandatory = $true)]
         [ValidateNotNullOrEmpty()]
         [System.Management.Automation.PSCmdlet]
         $CallerPSCmdlet,
 
-        [parameter(Mandatory = $true)]
+        [Parameter(Mandatory = $true)]
         [ValidateNotNullOrEmpty()]
         [System.String]
         $ExceptionName,
 
-        [parameter(Mandatory = $true)]
+        [Parameter(Mandatory = $true)]
         [ValidateNotNullOrEmpty()]
         [System.String]
         $ExceptionMessage,
         
         [System.Object]
         $ExceptionObject,
         
-        [parameter(Mandatory = $true)]
+        [Parameter(Mandatory = $true)]
         [ValidateNotNullOrEmpty()]
         [System.String]
         $ErrorId,
 
-        [parameter(Mandatory = $true)]
+        [Parameter(Mandatory = $true)]
         [ValidateNotNull()]
         [System.Management.Automation.ErrorCategory]
         $ErrorCategory
     )
         
-    $exception = New-Object $ExceptionName $ExceptionMessage;
+    $exception = New-Object -TypeName $ExceptionName -ArgumentList $ExceptionMessage
     $errorRecord = New-Object System.Management.Automation.ErrorRecord $exception, $ErrorId, $ErrorCategory, $ExceptionObject
     $CallerPSCmdlet.ThrowTerminatingError($errorRecord)
 }
 ```
 
-
 #### Use SupportsShouldProcess when appropriate
-Discuss: when is this critical (-whatif) and optional (-confirm_
-Discuss: when should you call PSCmdlet.ShouldProcess vs PSCmdlet.ShouldContinue (-Force)
+Discuss: when is this critical (-WhatIf) and optional (-Confirm)
+Discuss: when should you call $PSCmdlet.ShouldProcess vs $PSCmdlet.ShouldContinue (-Force)
 
 ```
 [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = "Medium")]
 param([Switch]$Force)
 
-$RejectAll = $false;
-$ConfirmAll = $false;
+$RejectAll = $false
+$ConfirmAll = $false
 
-foreach($file in ls) {
+foreach ($file in ls) {
 
-   if($PSCmdlet.ShouldProcess( "Removed the file '$($file.Name)'",
+   if($PSCmdlet.ShouldProcess("Removed the file '$($file.Name)'",
                                "Remove the file '$($file.Name)'?",
-                               "Removing Files" )) {
+                               "Removing Files")
+   ) {
 
-      if($Force -Or $PSCmdlet.ShouldContinue("Are you REALLY sure you want to remove '$($file.Name)'?", "Removing '$($file.Name)'", [ref]$ConfirmAll, [ref]$RejectAll)) {
+      if ($Force -Or $PSCmdlet.ShouldContinue("Are you REALLY sure you want to remove '$($file.Name)'?", "Removing '$($file.Name)'", [ref]$ConfirmAll, [ref]$RejectAll)) {
          "Removing $File"
 
 
@@ -242,36 +234,30 @@ The problems with this have gone away with autoloading, and this is the only way
 #### Persisting Configuration
 My choice: Configuration module. Otherwise, use clixml (or XAML) to persist to AppData (TEST: you shouldn't store configuration in your module folder, as it may not survive upgrades (in PowerShell 3 & 4 there was no side-by-side loading))
 
-
 #### Provide aliases in your modules
 You should feel free to create and use aliases within your modules. In some cases, you can even improve readability by using an alias without the verb, or shortening command names.
 
 For exported aliases, follow the guidance of Microsoft ("ip" for import, "s" for set, "g" for get, "r" for remove, etc.), make up something for your nouns.
 
 Use `New-Alias ... -ErrorAction SilentlyContinue` to avoid overwriting existing aliases.
 
-
-
-
 ### GOTCHAS
 
-#### Beware string concatenation with +
-You should always wrap this with parentheses, because otherwise it can break (e.g. when passing a string as a parameter.
+#### Beware of string concatenation with +
+You should always wrap this with parentheses, because otherwise it can break (e.g., when passing a string as a parameter).
 
-#### Beware -match and -like
+#### Beware of -match and -like
 They quietly cast objects to strings (or arrays of strings)
 
-#### Beware -contains and -in
-They work on ARRAYS not strings
-
+#### Beware of -contains and -in
+They work on ARRAYS, not strings
 
 ### Use Language Features
-When writing scripts (as opposed to at the command line), you should almost always choose language features over cmdlets. This includes using if instead of where-object, foreach instead of ForEach-Object, etc.
-
-The language features are always faster, and almost always more readable. Of course, there are always exceptions, and one exception to this rule is when using foreach will force you to collect a lot of items into an array instead of iterating them as they stream through a pipleine.
+When writing scripts (as opposed to at the command line), you should almost always choose language features over cmdlets. This includes using `if` instead of `Where-Object`, `foreach` instead of `ForEach-Object`, etc.
 
+The language features are always faster, and almost always more readable. Of course, there are always exceptions, and one exception to this rule is when using `foreach` will force you to collect a lot of items into an array instead of iterating them as they stream through a pipeline.
 
-### You should understand the .Net underpinnings
+### You should understand the .NET underpinnings
 
 #### AVOID appending to string in a loop
 ##### INSTEAD assign output from the loop using $OFS
@@ -283,19 +269,17 @@ The language features are always faster, and almost always more readable. Of cou
 * Joining an array of strings is fast
 * Easier to read and understand
 
+### Strongly typed parameters
+Although PowerShell is a dynamic language, we can specify types, and in parameters, it's particularly useful because it hints to users what they can pass to your command.
 
-### Strongly type parameters
-Although PowerShell is a dynamic language, we have can specify types, and in Parameters, it's particularly useful because it hints to users what they can pass to your command.
-
-Strong types on parameters is also crucial because it's a user-input point.  Strong types can help you avoid script injection and various other problems with user inputs, and will allow failures to happen as early as possible (even before your command is called).
+Strong types on parameters is also crucial because it's a user-input point. Strong types can help you avoid script injection and various other problems with user inputs, and will allow failures to happen as early as possible (even before your command is called).
 
 Additionally, avoid using `[string]` with ParameterSets because anything can be cast to it, so PowerShell can't distinguish one parameter set from the other.
 
-When passing on parameters to another command, you should be _at least_ as strongly typed as the other command, to avoid casting exceptions within your script.
+When passing on parameters to another command, they should be _at least_ as strongly typed as the other command, to avoid casting exceptions within your script.
 
 One notable exception is when you could accept more than one type. In PowerShell you can specify parameter set overloads, but you can't change the type of a parameter.
 
-
 ### Don't reinvent the wheel
-### Let's talk about Logging
-### Let's talk about code signing
+### Let's talk about logging
+### Let's talk about code signing