{"action":"created","issue":{"url":"https://api.github.com/repos/PoshCode/PowerShellPracticeAndStyle/issues/36","labels_url":"https://api.github.com/repos/PoshCode/PowerShellPracticeAndStyle/issues/36/labels{/name}","comments_url":"https://api.github.com/repos/PoshCode/PowerShellPracticeAndStyle/issues/36/comments","events_url":"https://api.github.com/repos/PoshCode/PowerShellPracticeAndStyle/issues/36/events","html_url":"https://github.com/PoshCode/PowerShellPracticeAndStyle/issues/36","id":84155723,"number":36,"title":"Capitalization guidelines","user":{"login":"KirkMunro","id":3515485,"avatar_url":"https://avatars.githubusercontent.com/u/3515485?v=3","gravatar_id":"","url":"https://api.github.com/users/KirkMunro","html_url":"https://github.com/KirkMunro","followers_url":"https://api.github.com/users/KirkMunro/followers","following_url":"https://api.github.com/users/KirkMunro/following{/other_user}","gists_url":"https://api.github.com/users/KirkMunro/gists{/gist_id}","starred_url":"https://api.github.com/users/KirkMunro/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/KirkMunro/subscriptions","organizations_url":"https://api.github.com/users/KirkMunro/orgs","repos_url":"https://api.github.com/users/KirkMunro/repos","events_url":"https://api.github.com/users/KirkMunro/events{/privacy}","received_events_url":"https://api.github.com/users/KirkMunro/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/PoshCode/PowerShellPracticeAndStyle/labels/Style%20Guide","name":"Style Guide","color":"0052cc"}],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":6,"created_at":"2015-06-02T18:56:35Z","updated_at":"2015-06-03T17:15:14Z","closed_at":null,"body":"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.\r\n\r\nHere 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:\r\n\r\n> Since nobody else is going first, here are my thoughts. Any disagreement?\r\n> \r\n> **Keywords (try, catch, foreach, switch)**\r\n> lowercase (rationale: no language other than VB uses mixed case keywords?)\r\n> \r\n> **Process Block Keywords (begin, process, end, dynamicparameter)**\r\n> lowercase (same reason as above)\r\n> \r\n> **Comment Help Keywords (.Synopsis, .Example, etc)**\r\n> PascalCase (rationale: readability)\r\n> \r\n> **Package/Module Names**\r\n> PascalCase\r\n> \r\n> **Class Names**\r\n> PascalCase\r\n> \r\n> **Exception Names (these are just classes in PowerShell)**\r\n> PascalCase\r\n> \r\n> **Global Variable Names**\r\n> $PascalCase\r\n> \r\n> **Local Variable Names**\r\n> $camelCase (see for example: $args and $this)\r\n> \r\n> **Function Names**\r\n> PascalCase\r\n> \r\n> **Function/method arguments**\r\n> PascalCase\r\n> \r\n> **Private Function Names (in modules)**\r\n> PascalCase\r\n> \r\n> **Constants**\r\n> $PascalCase\r\n> \r\n> I have doubts about Comment Help Keywords, and about is Constants.\r\n> \r\n> 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.\r\n> \r\n> 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\r\n> \r\n> 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 :wink: -- 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 ;-)\r\n\r\nI am 100% in agreement with all of this (now that I took the distracting parts out :wink:).\r\n\r\nThe 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:\r\n\r\nGet-AzureVMDscExtension\r\nGet-AzureVMDscExtensionStatus\r\nPublish-AzureVMDscConfiguration\r\nRemove-AzureVMDscExtension\r\nSet-AzureVMDscExtension\r\n\r\nMy 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:\r\n\r\nGet-AzureVmDscExtension\r\nGet-AzureVmDscExtensionStatus\r\nPublish-AzureVmDscConfiguration\r\nRemove-AzureVmDscExtension\r\nSet-AzureVmDscExtension\r\n\r\nIf 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:\r\n\r\nGet-AzureVMDSCExtension\r\nGet-AzureVMDSCExtensionStatus\r\nPublish-AzureVMDSCConfiguration\r\nRemove-AzureVMDSCExtension\r\nSet-AzureVMDSCExtension\r\n\r\nThere 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.\r\n\r\nAnyway, 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).\r\n\r\nSo, to keep it simple, two questions:\r\n1. Are there any objections to the proposed casing for the various PowerShell elements identified above?\r\n2. 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?"},"comment":{"url":"https://api.github.com/repos/PoshCode/PowerShellPracticeAndStyle/issues/comments/108528871","html_url":"https://github.com/PoshCode/PowerShellPracticeAndStyle/issues/36#issuecomment-108528871","issue_url":"https://api.github.com/repos/PoshCode/PowerShellPracticeAndStyle/issues/36","id":108528871,"user":{"login":"KirkMunro","id":3515485,"avatar_url":"https://avatars.githubusercontent.com/u/3515485?v=3","gravatar_id":"","url":"https://api.github.com/users/KirkMunro","html_url":"https://github.com/KirkMunro","followers_url":"https://api.github.com/users/KirkMunro/followers","following_url":"https://api.github.com/users/KirkMunro/following{/other_user}","gists_url":"https://api.github.com/users/KirkMunro/gists{/gist_id}","starred_url":"https://api.github.com/users/KirkMunro/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/KirkMunro/subscriptions","organizations_url":"https://api.github.com/users/KirkMunro/orgs","repos_url":"https://api.github.com/users/KirkMunro/repos","events_url":"https://api.github.com/users/KirkMunro/events{/privacy}","received_events_url":"https://api.github.com/users/KirkMunro/received_events","type":"User","site_admin":false},"created_at":"2015-06-03T17:15:14Z","updated_at":"2015-06-03T17:15:14Z","body":"@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. ;)"}}