Capitalization of function parameter type

[OCram85]

I'm currently working on a internal style guide for new colleagues and got stuck while comparing the capitalization content.
So I read the article and discussions here. And there is one aspect I couldn't find or just have missed.

Whats about the function parameter types like:

• String/string
• Integer/integer
• Switch/switch
• PSCustomObject/pscustomobject?

Should these be written in PascalCase oder is there difference between basic types and objects/classes? - In the code snippets of the Code-Layout-and-Formatting article they are in lowercase. So If i get this right, they should be in PascalCase because they match to the rule for .Net Class types, since pwsh types are basically .net Objects?

💡 Example:

function Invoke-FooBar {
    [CmdletBinding()]
    #[OutputType([String])]

    param (
        [Parameter(Mandatory = $true)]
        [String]$MyParam
    )

    begin {
    }

    process {
    }

    end {
    }
}

[Jaykul]

As a general rule: use the native capitalization for type names. The easiest implementation of that is to use the tab-completion value. This assumes you're using the built-in tab-completion...

Normally, that results in PascalCase, but for accelerators it's lowercase. Here's a few examples you're probably familiar with:

Key                   Value
---                   -----
array                 System.Array
bool                  System.Boolean
double                System.Double
float                 System.Single
single                System.Single
guid                  System.Guid
hashtable             System.Collections.Hashtable
int                   System.Int32
int32                 System.Int32
int16                 System.Int16
long                  System.Int64
int64                 System.Int64
string                System.String

The reason for this is rooted in the way C# has "native" types which must be written in lowercase. However, in PowerShell they're not native types, they're just accelerators (aliases). Most of the accelerators that were added originally in Windows PowerShell were all lowercase.

There are some built-in accelerators which were added later that are not full lowercase (personally, I prefer to type these in all lowercase too, to help remember what they are). If you run PowerShell -NoProfile you can get a list of them like this:

<# PS C:\ #> [psobject].assembly.
gettype("System.Management.Automation.TypeAccelerators")::
get.GetEnumerator().
Where{ $_.Key -cmatch '^[A-Z]' -and $_.Value.Name -notmatch 'Attribute$' } | 
Sort Key

Key                   Value
---                   -----
CimSession            Microsoft.Management.Infrastructure.CimSession
IPEndpoint            System.Net.IPEndPoint
NullString            System.Management.Automation.Language.NullString
ObjectSecurity        System.Security.AccessControl.ObjectSecurity
PhysicalAddress       System.Net.NetworkInformation.PhysicalAddress
WildcardPattern       System.Management.Automation.WildcardPattern
X500DistinguishedName System.Security.Cryptography.X509Certificates.X500DistinguishedName
X509Certificate       System.Security.Cryptography.X509Certificates.X509Certificate
ExperimentAction      System.Management.Automation.ExperimentAction
ExperimentalFeature   System.Management.Automation.ExperimentalFeature

The last two of those were added in PowerShell 7.1 ...

In addition to those, all of the attributes are written with PascalCase.

Since accelerators can be changed, and since you can always leave off the System namespace (intentionally or inadvertently), I like to be slightly more consistent than "whatever tab completion outputs". If you're like me, here are the detailed rules:

1. Use using namespace if you want to skip entering the full name.
2. Prefer the full name and native capitalization of the type (which is always PascalCase,)
   • Don't leave off System
   • You can check the .FullName property of the type.
3. Always use PascalCase for attributes
4. Use full lowercase when using an accelerator

The attributes we use frequently in PowerShell are all short names (think of CmdletBinding, Parameter, Alias, and the Validate* attributes). Those are always entered uniformly PascalCase, matching the original case of the type, so I just stick to that for attributes.

If we're consistent, we will be reminded by the [lowercasetype] that we're dealing with an accelerator, and everything else has the proper full name, which will match what's in docs.microsoft.com, etc., except attributes, which are always accelerators.

Obviously the only thing that differs from the initial answer are those 8-10 classes that aren't attributes but were accelerated with PascalCase anyway. These types are pretty rarely used, so most of the time you won't be able tell the difference. Having said that, the easiest way to achieve consistency is to just recreate the non-uniform accelerators the way that you want them, and always use the built-in tab completion, here's the snippet you need for that 😁

$xlr8 = [psobject].assembly.gettype("System.Management.Automation.TypeAccelerators")
@($xlr8::get.GetEnumerator()).Where{ $_.Key -cmatch '^[A-Z]' -and $_.Value.Name -notmatch 'Attribute$' }.ForEach{ 
    $null = $xlr8::remove($_.Key)
    $null = $xlr8::add($_.Key.ToLower(), $_.Value)
}

Of course, since PowerShell is not C#, and these aren't actually native types, you could hypothetically choose to achieve consistency the other way: rewrite all the accelerators to use the native PascalCase names. That would not match the normal community conventions, but I think that if you wanted to make that the rule within a project or an organization, it wouldn't be too hard to enforce.

[OCram85]

Wow, thank you so much for this awesome detailed explanation 🎉

So If I get this right, the common way would be:

• Use lowercase for basic types provided via accelerators ( like. string, int, bool)
• Use PascalCase as standard for all other Types/ Objects. ([PSSCustomObject], [MailAddress])
• Use PascalCase for common used Attributes like [CmdletBinding()], [ValidateNotNullOrEmpty()]