Capitalization guidelines

[KirkMunro]

So, there was a useful post by @Jaykul on #17 that got lost amid some debates that were not relevant to that specific discussion. This just came up again for me while watching a live demonstration where I realized I really didn't like the capitalization guidelines they followed, so I thought I'd try to refocus the discussion on this since we never did come to a consensus.

Here is Jaykul's post on this (slightly modified to remove points of contention that derailed the other issue), copied so that you don't have to go look it up:

Since nobody else is going first, here are my thoughts. Any disagreement?

Keywords (try, catch, foreach, switch)
lowercase (rationale: no language other than VB uses mixed case keywords?)

Process Block Keywords (begin, process, end, dynamicparameter)
lowercase (same reason as above)

Comment Help Keywords (.Synopsis, .Example, etc)
PascalCase (rationale: readability)

Package/Module Names
PascalCase

Class Names
PascalCase

Exception Names (these are just classes in PowerShell)
PascalCase

Global Variable Names
$PascalCase

Local Variable Names
$camelCase (see for example: $args and $this)

Function Names
PascalCase

Function/method arguments
PascalCase

Private Function Names (in modules)
PascalCase

Constants
$PascalCase

I have doubts about Comment Help Keywords, and about is Constants.

Comment help keywords have frequently been written in ALLCAPS to make them stand out more (the same is true for the process block keywords) one need only search poshcode to see examples of this. Personally, I think that if the indentation rules are followed, all of these keywords would be indented one level less than everything else around them, so there is no reason to capitalize them to make them stand out.

Constants are basically global variables which should not be changed. Hypothetically we can enforce non-changing on them. Note that Microsoft has several such constants and follows NO CONVENTION AT ALL: $Error, $ExecutionContext, $PID, $PSVersionTable, $ShellId, $Host, $PSHOME, $true, $false

I would argue that true and false are special, and that other than that, these are all PascalCase except $PSHOME which obviously should be $PSHome 😉 -- Hypothetically I'd be willing to use some other naming convention (like $ALL_CAPS or $Under_Score) but they would forever clash with the constants Microsoft has created ;-)

I am 100% in agreement with all of this (now that I took the distracting parts out 😉).

The only place where I have any question here is around case sensitivity with acronyms, which was not called out. According to the Microsoft standard for PascalCase and camelCase, if an acronym is two letters then you don't change the case, but if it is three or more then you do. That results in command names that look like this:

Get-AzureVMDscExtension
Get-AzureVMDscExtensionStatus
Publish-AzureVMDscConfiguration
Remove-AzureVMDscExtension
Set-AzureVMDscExtension

My brain has a really hard time delineating between VM and Dsc in those command names. I always see VMD sc. Personally, I follow these same PascalCase/camelCase rules, but for acronyms I always put every character beyond the first as lowercase, to make the identifiers more readable. For example, I would have named all of the above commands like this:

Get-AzureVmDscExtension
Get-AzureVmDscExtensionStatus
Publish-AzureVmDscConfiguration
Remove-AzureVmDscExtension
Set-AzureVmDscExtension

If I was to place an exception on anything related to acronyms, it would be PS, because, well, PowerShell. Either that or I would modify Microsoft's rule, indicating that you only maintain case on an acronym if the acronym is 2 characters long, and when maintaining case any acronyms immediately after that one must use the same case. With that, the commands would instead look like this:

Get-AzureVMDSCExtension
Get-AzureVMDSCExtensionStatus
Publish-AzureVMDSCConfiguration
Remove-AzureVMDSCExtension
Set-AzureVMDSCExtension

There are examples of this in native PowerShell cmdlets as well, but for those examples, the acronym is at the beginning of the noun which seems easier to identify than when it is in the middle with mixed case acronyms side by side.

Anyway, we should explicitly decide how we want acronyms to be cased when using Pascal or Camel case. My vote would be to always make every character after the first in acronyms lowercase (like I show in the second example above), but I'll follow whatever the community decides, and I realize it would probably be best if we simply followed Microsoft's guidelines for consistency here (even if I don't like them).

So, to keep it simple, two questions:

1. Are there any objections to the proposed casing for the various PowerShell elements identified above?
2. Do you think we should follow Microsoft's guidelines for acronyms wrt Pascal and Camel case or is that some horrible Kool-Aid that we should throw away in favor of always lowercasing every character in every acronym beyond the first when applying Pascal or Camel case to these elements?

[Jaykul]

I think I agree that Acronyms shouldn't get a pass on capitalization -- especially if they're strung together like that (stop kidding yourself: two capitalized acronyms together = one long acronym). In my head, I thought I was ok with capitalizing acronyms ... but when they run into another capital letter it makes things confusing, so ...

I'm fine with Get-AzureVmDscExtension as a recommendation over any of the other capitalization options. Treat acronyms like words. Period.

[rkeithhill]

The .NET Framework design guidelines recommend all caps for two letter acronyms e.g. IO as in System.IO and IP as in IPAddress. Do we want to follow that recommendation? If so the example cmdlet would be Get-AzureVMDscExtension.

[KirkMunro]

@rkeithhill: You didn't read my post, did you? :)

[rkeithhill]

Sorry man, tl;dr I do have a day job ya know. :-) Anyway, I was responding to Joel's recommendation of Get-AzureVmDscExtension. FWIW given that PowerShell is based on .NET and uses .NET types, I would be more inclined to follow the .NET FDG for casing guidance.

[rkeithhill]

BTW I'll also add that it is going to look funny having a set of recommendations that fly in the face of the existing Microsoft names i.e. all the Hyper-V VM cmdlets that come from Microsoft. Then there all the NetIPAddress, NetIPHttpsConfiguration, NetIPInterface, cmdlets. Seems to me this decision has already been made by Microsoft.

[KirkMunro]

@rkeithhill Right, as was discussed in my post (where "Joel's recommendation" came from). You could have just responded to the two questions at the bottom of that post and that would have worked too. ;)

And FWIW, I don't necessarily think that Microsoft's Acronym casing guidelines were really considering readability when you have multiple acronyms adjacent to one another in a very long string.

[Jaykul]

Because who would do that!?

And FWIW, I don't necessarily think that Microsoft's Acronym casing guidelines were really considering readability when you have multiple acronyms adjacent to one another in a very long string.

[mattmcnabb]

I vote for simplicity of rules. True PascalCase for acronyms (Get-AzureVmDscExtension). I'm not sure what is gained by having separate rules for two-character acronyms, other than rule complexity.

[sqlchow]

1. Are there any objections to the proposed casing for the various PowerShell elements identified above?
   [sqlchow]: No objection, I quite like them. Only suggestion about constants is, maybe something like: $c_PascalCase or $cPascalCase; just to make it easier to identify as a constant when reading code? Hoping this doesn't open up a new can of worms.
2. Do you think we should follow Microsoft's guidelines for acronyms wrt Pascal and Camel case or is that some horrible Kool-Aid that we should throw away in favor of always lowercasing every character in every acronym beyond the first when applying Pascal or Camel case to these elements?
   [sqlchow]: We do not have to follow Microsoft's guidelines. Between Get-SQLBackupStatus and Get-SqlBackupStatus; I prefer the later Get-SqlBackupStatus.

[KirkMunro]

For constants I prefer PascalCase. Less noisy/distracting, and different from local variable names. Sure they can look like variable names in global/script scope, and they can look like function/script parameter/argument names, but to be honest, it doesn't make much of a difference since they aren't used as often in PowerShell as they are in other languages.

As for the builtin variables like $true, $false, and $PSHOME, I don't think we should recommend changing the case of those in scripts/functions because tab completion will put them in the capitalization as they are defined (unless they have been entered with an incorrect capitalization earlier in the script where they are being used).

[rkeithhill]

The .NET Framework Design Guidelines have been around for over a decade. I would use these casing guidelines for Identifiers i.e. nouns - https://msdn.microsoft.com/en-us/library/ms229043(v=vs.110).aspx Also, as I previously mentioned, I don't think it's a good idea to come up with guidelines that would fail many of the built-in nouns. I know many folks have their "personal" preference - fine, name stuff using your personal preference but WRT to two letter acronyms - this train left the station a long time ago. I believe consistency in this case is "better than better".

WRT to constants, yeah I prefer PascalCase as well.

[sqlchow]

My bad for trying to push in the Hungarian notation for constants 😉

@rkeithhill:
Correct me if I am wrong. But, whilst trying to favour readability; PowerShell does not always strictly adhere to the .NET Framework Design guidelines. Because, if we did, we would have had parameter names like useTransaction or showWindow instead of UseTransaction or ShowWindow.

So, I believe a little flexibility may not be a bad thing. 😄

[Jaykul]

Actually, @sqlchow, I those are capitalized because PowerShell Cmdlet parameters are properties of the underlying .Net class implementations. When we got the ability to write advanced functions in PowerShell code, we used PascalCase for parameters so they would match the class-based commands...

[sqlchow]

@Jaykul thanks for letting me know 👍 I was under a completely different assumption until now.

This clears up a few things for me. Then I will go with @rkeithhill 's suggestions for using .NET naming conventions for two letter acronyms.

[pixelrebirth]

I agree with the eg:
Get-ADDNSName should be Get-AdDnsName

Here is what I would like to see for variables:

$localVariable ( eg. $inputValueInBar )
$GlobalVariable ( eg. $MathCounterInFoo )
$VariableConstant ( eg. $DigitInFooConstant or a local $digitInFooConstant ) 

Variable naming is by far the MOST important component of readable code... and please someone put an end to:

foreach ($c in $DeckOfCards) {Get-Suite $c}

This is horrible--- stop being lazy and just write $Card or $EachCard!

foreach ($Card in $DeckOfCards) {Get-Suite $Card}

[GrahamHannington]

When you add these guidelines, I would prefer to see them formatted as a table, so that I can see the cases by looking down a single column. For example:

Identifier	Case	Examples and notes
Language keyword	Lower	try, catch, foreach, switch No language other than VB uses mixed-case keywords
Process block keyword	Lower	begin, process, end, dynamicparameter As above
Comment help keyword	Pascal	.Synopsis, .Example Readability
Package or module	Pascal	PascalCase
Class	Pascal	PascalCase
Exception	Pascal	PascalCase
Global variable	Pascal	$PascalCase
Local variable	Camel	$camelCase, $args, $this
Function	Pascal	PascalCase
Function or method argument	Pascal	PascalCase
Private function	Pascal	PascalCase (in modules)
Constant	Pascal	$PascalCase

I initially had "Examples" and "Notes" as two separate columns, but decided to combine them.

I understand some people might have reservations about my use of <br> in the table Markdown.

I know there's some redundancy between the Case column and the examples. I can live with that. Although what I'd prefer is for the examples to be more specific than PascalCase.

I left the Item values as plural (I was tempted to make them singular), but I did convert them to sentence style (in prose, I personally favor sentence style to initial capital letters).

Update: I've given in to temptation 😄 and made the Item values singular. I've also, after revisiting the Microsoft .NET Capitalization Conventions, changed the Item column heading to Identifier, and removed the (to me, redundant) "name(s)" suffix from the values. I baulked at replacing Case with Casing. Perhaps I'd change my mind after a glass of Kool-Aid followed by a double shot of Victory Gin. I've also hyphenated the compound adjective "mixed-case". I need a drink...

I considered the following column layout for readability:

Identifier	Camel	Lower	Pascal	Examples and notes
Keyword		✅		try, catch, foreach, switch No language other than VB uses mixed case keywords

but rejected it as too onerous and error-prone for editing.

[darkoperator]

Like the idea of the table. Many people use code snippets included in ISE and in Visual Studio Code, in some cases they don’t match each other should we consider also making some of this style guide recommendations optional? Case that comes to mind is the process block and comment block keywords.

On Mar 17, 2016, at 11:54 PM, Graham Hannington [email protected] wrote:

When you add these guidelines, I would prefer to see them formatted as a table, so that I can see the cases by looking down a single column. For example:

Item Case Examples and notes
Keywords Lower try, catch, foreach, switch
No language other than VB uses mixed case keywords
Process block keywords Lower begin, process, end, dynamicparameter
As above
Comment help keywords Pascal .Synopsis, .Example
Readability
Package/Module names Pascal PascalCase
Class names Pascal PascalCase
Exception names Pascal PascalCase
Global variable names Pascal $PascalCase
Local variable names Camel $camelCase, $args, $this
Function names Pascal PascalCase
Function/method arguments Pascal PascalCase
Private function names Pascal PascalCase
(in modules)
Constants Pascal $PascalCase
I initially had "Examples" and "Notes" as two separate columns, but decided to combine them.

I understand some people might have reservations about my use of
in the table Markdown.

I know there's some redundancy between the Case column and the examples. I can live with that.

I left the Item values as plural (I was tempted to make them singular), but I did convert them to sentence style (in prose, I personally favor sentence style to initial capital letters).

I considered the following column layout for readability:

Item Camel Lower Pascal Examples and notes
Keywords try, catch, foreach, switch
No language other than VB uses mixed case keywords
but rejected it as too onerous and error-prone for editing.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub #36 (comment)

[nightroman]

Minor correction: change dynamicparameter to dynamicparam.

[GrahamHannington]

Compare:

Microsoft .NET Framework Capitalization Conventions

with:

Google Java Style

Google Style uses the terms upper camel case and lower camel case. I believe that upper camel case and Pascal case - or, if you prefer (I don't! 😄 ) PascalCase - are synonymous. (Please correct me if I'm wrong.)

While I like the "(nearly) deterministic" nature of the Google scheme, I think that PowerShell should follow the .NET conventions because of their close relationship. Here is the value of the content attribute of the Microsoft PowerShell home page <meta name="Description"> tag:

Microsoft PowerShell is an automation and scripting platform for Windows built on top of the object-oriented power of the .NET Framework.

According to the .NET conventions ("A special case (sic 😄 ) is made for two-letter acronyms in which both letters are capitalized"):

IOStream
HtmlTag

whereas, according to Google (no such special case):

IoStream
HtmlTag

[KirkMunro]

Ugh, I still prefer no special case, despite standards that I usually try to follow. When the examples are short like what you showed above representing something that looks like property names or variable names, it isn't that big a deal; however, in PowerShell it is not uncommon at all to have multiple adjacent acronyms, and when there are two-letter acronyms among those that are adjacent, the identifiers just become fugly.

Some examples that may or may not be real PowerShell commands:

• Get-ADDCIPAddress
• Get-AzureVMDscExtension
• Reset-TcpIPStack

The biggest problem IMHO is that this special case rule is going to be missed by the vast majority of command authors out there, who have already demonstrated difficulty in understanding why nouns should not be pluralized, ever.

Standards do need to evolve/adapt as needs change, and as mentioned earlier, it is very doubtful that this standard came about with thoughts toward what multiple adjacent acronyms in a single identifier would look like. It certainly wasn't created as a standard for scripters-not-developers to follow.

For this community, I still feel the only successful path forward wrt command names is to keep it as simple as possible, and keeping it simple means no special case for acronyms regardless of how many letters they have, just as there is no special case for pluralization of nouns. That's a much easier battle to fight (even though it is still difficult to make others understand that -- heck, there are still plenty of PowerShell MVPs who use pluralized nouns in their work), and it is much more likely to be adopted if acronyms are always handled the same way (have a look around for how many commands there are that have acronyms with more than 2 letters that are all capitalized -- there are plenty). Consistency and ease of use (having it easier to follow) within the PowerShell command set is more important than adhering to this piece of the .NET standard that seems questionable.

[rkeithhill]

The biggest problem IMHO is that this special case rule is going to be missed by the vast majority of command authors out there

Except for one particularly important author - Microsoft! Frankly I think it would look silly to adopt a convention that many of the built-in commands will fail. It is obvious that Microsoft is following this .NET FDG rule for all of the AD, BC, VM and IP related commands.

Ugh, I still prefer no special case

This is not about what @KirkMunro personally does not like. ;-)

[KirkMunro]

I know it's not about me personally. I'm not the only one who doesn't like this for PowerShell. I'm just being more vocal about it.

Except for one particularly important author - Microsoft!

You're kidding, right @rkeithhill? Microsoft publishes commands with pluralized nouns and misses naming standards, even when it comes to acronyms. All. The. Time. You can point to the AD, BC, VM, and IP related commands, which for the most part follow the standard except for some exceptions. But there are plenty of commands that come from Microsoft that don't follow said standard.

Here is a sampling of examples from Microsoft modules on my Windows 10 system that don't follow the standard you're proposing:

From the PowerShellISE-preview module:
Install-ISEPreviewShortcuts
Install-ISEPreviewShortcut
Start-ISEPreview

From the Azure module:
Get-AzureRemoteAppVmStaleAdObject
Get-AzureStorageCORSRule
Get-AzureVirtualNetworkGatewayIPsecParameters
New-AzureSSHKey
New-WAPackVNet

Azure.Storage:
New-AzureStorageFileSASToken
New-AzureStorageQueueSASToken
Remove-AzureStorageCORSRule
Set-AzureStorageCORSRule

All AzureRM.* modules:
Use a noun prefix of "AzureRm".

BranchCache module:
Set-BCMinSMBLatency

CimCmdlets module:
Import-BinaryMiLog

Defender module:
Noun prefix of "Mp" for all commands.
Start-MpWDOScan

Dism:
Set-AppXProvisionedDataFile

MSOnline:
Set-MsolADFSContext

NetAdapter:
Get-NetAdapterSriovVf

NetEventPacketCapture:
Add-NetEventWFPCaptureProvider
Get-NetEventWFPCaptureProvider
Remove-NetEventWFPCaptureProvider
Set-NetEventWFPCaptureProvider

netsecurity:
Get-NetIPsecMainModeSA
Get-NetIPsecQuickModeSA
Open-NetGPO
Remove-NetIPsecMainModeSA
Remove-NetIPsecQuickModeSA
Save-NetGPO
Set-NetIPsecDospSetting
Get-DAPolicyChange

NetTCPIP:
Get-NetTCPConnection
Get-NetUDPEndpoint

NetworkConnectivityStatus:
Get-DAConnectionStatus
Get-NCSIPolicyConfiguration

SecureBoot:
Confirm-SecureBootUEFI

Storage:
Get-DiskSNV

WebAdministration:
Get-WebURL

SQLPS:
New-SqlHADREndpoint

There are definitely others as well in modules I simply don't have installed.

[mattmcnabb]

I think it's preferable to avoid the special case for capitalization of two-letter acronyms. I'm aware of the .Net conventions that @rkeithhill is referring to, but disagree with them simply because there is no reason given as to why these need a special case. @KirkMunro is absolutely right that these types of special case rules are hard to justify and endorse.

That said I have used this convention myself simply because there has always been a lack of a set of guidelines like this project, but now is our chance to break from tradition.

[rkeithhill]

@KirkMunro I'm only referring to the two letter, upper case example. The vast majority of your examples demonstrate improper casing of >2 character acronyms/abbreviations. In fact, what's wrong with the *-MMAgent names?

Sure, there are some badly named cmdlets. But those are not the examples we want to follow, right? Or perhaps we can't agree those are examples of doing it "wrong"? Sigh...

FWIW I don't believe some "bad" examples of deviation from the "norm" within the set of built-in commands provided by Microsoft makes a good argument for declaring the "norm" as wrong.

WRT to the rest of the casing rules - I'm in agreement. Maybe this rule (2 letter acronym special case) is too subjective (like line length) where we can't agree on a standard recommendation. I know I will continue to follow the established norm as I see it as established by Microsoft. And I highly suspect the majority of Microsoft commands will continue to follow the 2 letter acronym upper case rule. Now if Microsoft adopts a different policy WRT to this rule, I'll happily switch to that. :-)

[rkeithhill]

@mattmcnabb RE:

aware of the .Net conventions that @rkeithhill is referring to, but disagree with them

I good friend and manager of mine (now passed) used to say "standard is better than better". Not everybody can get their "personal" preference because it is rare that everybody will agree. :-)

It would be one thing if PowerShell had just started in Beta and we were starting this from "scratch" - feeding back to Microsoft what casing conventions we wanted them to use for commands. But we are not. As @KirkMunro points out, Microsoft is not terribly consistent mainly because you have teams other than the PowerShell team contributing commands. However the PowerShell team set the standard when they shipped: *-PSBreakpoint, *-PSCallStack, *-PSDrive, *-PSSession*, *-PSRole*, *-PSSnapin, *-PSRemoting as far as I'm concerned.

Frankly, for the "community" to recommend against the "defacto standard" is rather silly IMO like trying to close the barn door after the horses are all gone. :-)

[KirkMunro]

@rkeithhill You're right about the *-MMAgent commands. I built that example list quickly, and left a few commands in that I shouldn't have. I edited the list above removing those that shouldn't be there.

I agree with following standards. I stray because I'm not 100% convinced that the .NET guidelines/standards are the PowerShell guidelines/standards. We're looking at one example: capitalization. But PowerShell has its own guidelines/standards, and in those standards they don't even talk about capitalization. Back in the PS v1 days, there were some commands with acronyms (-PS commands), and Quest created the -QAD commands (while working with Microsoft because they were filling a gap), without any specific mention of a capitalization standard. The norm (not the standard) at that time seemed to be to capitalize all acronyms, regardless of length. Other groups inside Microsoft also used all caps for acronyms, and also regardless of their length, particularly in the System Center set of servers, and many of those are still around. So from my perspective, you're pointing to .NET guidelines and saying "that's the standard" when the community/Microsoft hasn't even come out with a standard for this yet, so as far as .NET guidelines go I'm saying "that is a standard, but it isn't necessarily the standard for PowerShell" command names. In deciding upon a standard to use (since we're developing best practices here) it is worth considering all pros/cons and making sure we make the right choice. PowerShell is built on top of .NET, but the .NET aspect of it is only an implementation detail to many -- it isn't quite like other .NET programming languages. While I wish PowerShell were a programming language, is really is just a scripting language -- different rules, different use cases, plenty of issues that make it fall apart when programming is concerned. Does PowerShell also follow all of the rest of the .NET guidelines that you're pulling this out of? Or only this one, and only for a decent-sized subset of commands that come in Windows, while hundreds of others also from Microsoft that aren't shipped with Windows don't follow this particular capitalization "standard"?

No matter which way this issue goes, it's messy because there are plenty of commands on either side of the fence that would then be seen as out of compliance with the standard, so we should make the right choice for PowerShell, not by cherry-picking one portion of a larger standard that isn't even adhered to in Microsoft-produced modules and that might not be best applied to PowerShell, but by picking the best choice for PowerShell going forward.

[nightroman]

Just a remark. Presumably, .Net names of stuff will leak to PowerShell when it uses some libraries. So if these names follow .Net naming (likely) then it will be easier if PowerShell naming is the same. It would be annoying and confusing to change capitalization just because PowerShell follows different rules.

[rkeithhill]

@KirkMunro So you'd propose that these commands:

*-PSBreakpoint, *-PSCallStack, *-PSDrive, *-PSSession*, *-PSRole*, *-PSSnapin, 
*-PSRemoting, *-PSRepository

should be cased like this:

*-PsBreakpoint, *-PsCallStack, *-PsDrive, *-PsSession*, *-PsRole*, *-PsSnapin, 
*-PsRemoting, *-PsRepository

I dunno. These commands may be few in numbers but some of them are bread & butter (core) commands.

That aside, can we all agree that all the other casing rules (except for 2 letter acronyms) are good?

Well OK, there is another one that should be discussed and that is comment help keywords. The standard suggests Pascal but if you look at help on the built-in commands, these keywords are displayed ALL_CAPS. Should we use the same ALL_CAPS casing for comment help keywords? I see that platyPS also generates help with SYNOPSIS, DESCRIPTION, etc.

[KirkMunro]

I think all other casing rules are agreed upon, but you brought up a valid point about comment help keywords. Not only are they displayed in ALL_CAPS in the help that is generated, and in platyPS, but they are applied in ALL_CAPS in about_comment_based_help (https://technet.microsoft.com/en-us/library/hh847834.aspx) as well. With that being the case, it seems that ALL_CAPS is the way to go for comment-based help keywords. Disclaimer: I already use ALL_CAPS for comment-based help keywords, but I believe my comments here to be unbiased. :)

Believe it or not, I'm on the fence for the command name capitalization standard, because I don't see a clear winner in either case, and because there are enough arguments that are good on both sides. Maybe we should put it to a vote on Twitter for a week and go with the winner. Either that or ask Microsoft to step in and declare their wishes as far as a capitalization standard goes. Or both. I'll reach out to someone who I think may help make that decision so that we can move forward on this, because I think the community will be much better off with a well defined standard for command naming that includes capitalization rules.

[mattmcnabb]

I second the ALL_CAPS in comment-based help keywords.

The reasoning is that because the help will be a string, there is no syntax highlighting to help the eye differentiate the help text from the keywords. ALL_CAPS helps you scan to find the keywords.

I also like to make sure that I have spaces before each new keyword, but that's not germane to this topic.

[rkeithhill]

@KirkMunro Sounds like a plan. I definitely recommend reaching out to Microsoft (ie the PowerShell team).

[ghost]

For the general naming (ignoring the help), the proper answer for PowerShell has been to align with the .Net coding guidelines. This has been true for a while (see: https://msdn.microsoft.com/en-us/library/dd878270(v=vs.85).aspx). As for what that means, it's what's cited in the .Net casing reference in MSDN (https://msdn.microsoft.com/en-us/library/ms229043(v=vs.110).aspx) that treats acronyms as words if they are longer than 2 characters. 2-Character acronyms are left as caps.
I also did some back-research & Pascal casing guidelines were created to try to improve readability when things are being scanned. The .Net description is right approach, & is either referenced by or consistent with the other references I could find (StackOverflow: http://stackoverflow.com/questions/15526107/acronyms-in-camelcase, Quora: https://www.quora.com/How-should-you-camel-case-an-acronym, and Wikipedia: https://en.wikipedia.org/wiki/CamelCase#In_abbreviations_and_acronyms ).
I can't speak to the help naming right now. I will have to do some more research, & would prefer to give a thorough answer, as in this situation.

[nogeekleftbehind]

Did anyone reach out and hear back from the PowerShell team? It's been a few years.
FWIW - The sample PowerShell scripts located here are using camelCaps (with the exception of $OKButton and $CancelButton):
https://docs.microsoft.com/en-us/powershell/scripting/samples/creating-a-custom-input-box
Dated 06/05/2017

[Jaykul]

So what you're saying, @nogeekleftbehind, is that the docs don't follow any style standard at all? Unfortunately, the PowerShell team has never been willing to follow this guide, and they have published different guides for each project they manage -- so it's hardly surprising that they can't maintain consistency in the docs. 😑 I filed MicrosoftDocs/PowerShell-Docs/issues/5467 because I think that at least within the same page they need to follow the same standard.

For what it's worth, we have said this (emphasis mine):

If you wish, you may use camelCase for variables within your functions (or modules) to distinguish private variables from parameters, but this is a matter of taste.

But I would never let that code example you linked to through a code review, because of the inconsistency. Use camelCase or PascalCase for private variables -- but not both.

P.S. Ugh. Allman Braces...