encourage instead of discourage alias

[rismoney]

https://github.com/PoshCode/PowerShellPracticeAndStyle/blob/master/Style-Guide/Naming-Conventions.md

Idiomatic powershell should be encouraged, and the only substantive reason for discouraging a particular alias is compatability issue across versions. (PSCore/Standard).

Summary: use aliases everywhere and encourage people to use powershell in new and fun ways.

[ChrisLGardner]

The big reasons for discouraging aliases is readability and maintainability. You can't guarantee anyone coming along later will know what a particular alias means and that will act as a barrier to others maintaining and using your code.

Aliases are perfectly fine on the command line where you're running tasks quickly and usually one off.

---

From: Rich Siegel [email protected] Sent: Tuesday, April 24, 2018 6:48:32 PM To: PoshCode/PowerShellPracticeAndStyle Cc: Subscribed Subject: [PoshCode/PowerShellPracticeAndStyle] encourage instead of discourage alias (#108)

https://github.com/PoshCode/PowerShellPracticeAndStyle/blob/master/Style-Guide/Naming-Conventions.md

Idiomatic powershell should be encouraged, and the only substantive reason for discouraging a particular alias is imcompatability across versions.

Summary: use aliases everywhere and encourage people to use powershell in new and fun ways.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHubhttps://github.com/PoshCode/PowerShellPracticeAndStyle/issues/108, or mute the threadhttps://github.com/notifications/unsubscribe-auth/AQDqFk3y74jwnPP7ag66FWFK2rFCQYdmks5tr2VwgaJpZM4TiIVr.

[lipkau]

My take on this is that using aliases is discuraged... not defining them

[rismoney]

I disagree. Using aliases should be encouraged.

The big reasons for discouraging aliases is readability and maintainability. You can't guarantee anyone coming along later will know what a particular alias means and that will act as a barrier to others maintaining and using your code.

The versions of full powershell have a set of consistent built in aliases that are ....built in. Example, % and ? should be used excessively and everywhere. The vast community has this discouraged in scripts incorrectly. The only reason to not use a specific subset of items, would be deprecation of aliases which is only a thing in the PS vs PSCore limited use scenario. I'd challenge any other use case as fake news.

[lipkau]

I should have been more clear: when writing a script, function or module

[michaeltlombardi]

There is also a performance hit associated with using aliases and a general lossiness of use. It costs the writer of scripts/functions very little to expand an alias to the referent function.

Also, use of aliases makes no sense if you're fully qualifying commands which is another thing we should be doing in scripts and functions.

Best practice at the prompt != best practice in a script file.

[pauby]

You can't guarantee anyone coming along later will know what a particular alias means

Complete agreement.

But you also can't guarantee that the alias you're using in your code is the same alias on my system. Aliases are designed for me to customise my environment to my liking for me. They are not for developers to use as a shortcut because they don't care about the end user.

[rismoney]

You can't guarantee anyone coming along later will know what a particular alias means

Fallacy. Get-help % is no different than get-help foreach-object. If someone doesn't know what something means the help system is built for this.

Also, use of aliases makes no sense if you're fully qualifying commands which is another thing we should be doing in scripts and functions.

The performance issue of alias resolution in all but edge cases I'd argue as overblown. I will quantify it in a subsequent message for full disclosure but that's like saying - abandon PScmdlet for native dotnet functions since they'll be faster than ps wrapped stuff.

Using Where-Object isn't safer than ? You can override Where-Object by just defining a func -- in fact, it's easier to override the cmdlet name than the alias. No -Force and -Option AllScope required. So aliases are safer in this regard. More FUD.

[OraDotNetDev]

As far as I was aware, the use case for aliases is as a convenience for interactive use in the shell.

Built-in commands can be over-ridden. However this is much less common (and also bad practice) and if anything leads to the suggestion that you use Fully Qualified references for all your commands ie Microsoft.PowerShell.Core\Get-Command . There's definitely a case been made that you should be doing that for your own modules.

Never-mind the confusion of PowerShell newbies searching Google for "Powershell %" and understanding what this construct means.

Paraphrasing slightly avoiding aliases (and .Net) should result in code which balances performance and terseness against maintainability, consistency, predictability, readability and reliability "especially for users who do not speak English as a first language. "

Or understanding what the commands below do, especially when the last command becomes ri -Fo -R

sl -Path $env:TEMP; gci -Path (gl) | % { $_.FullName } | ri -Wh -R

[pauby]

The vast community has this discouraged in scripts incorrectly. The only reason to not use a specific subset of items, would be deprecation of aliases which is only a thing in the PS vs PSCore limited use scenario.

That's a very valid reason for discouraging them. PS vs PSCore is not a limited use scenario

I'd challenge any other use case as fake news. Fallacy More FUD.

You've had reasoned argument and then we get your responses above. You're not here for reasoned argument. You're here to impose your view and put down anybody else's who don't agree with you with comments like the above.

You're not listening and as such nobody is going to listen to you so your suggestions on aliases are not going to heard, they're not going to be taken seriously and they are not going to end in the 'best practice' guidelines being amended. As such we are all wasting our time in this thread.

There are ways and means of doing things and debating issues. This isn't it.

[rismoney]

I am listening and trying to convince the community to amend its stance. I'm trying to have a discussion, but I wonder if there are impedements from attentional, availability cascade, and status quo biases preventing meaningful dialog versus keeping a completely open mind.

That's a very valid reason for discouraging them. PS vs PSCore is not a limited use scenario

https://github.com/PowerShell/PowerShell/issues/5870

The fact here is that the community is not in agreement and therefore the ruling here should be to not preach practice and style that raises discourse. The rules for interactive usage and scripts cannot be dissimilar any more than the rules for PS vs PSCore are. You can't have the cake and eat it too.

Here's an example - https://github.com/majkinetor/au/pull/19 . I'm not surprised @pauby, since you created https://github.com/majkinetor/au/pull/89

As for a meaningful run-time performance difference between alias and not: I have found the difference between % and foreachobject across 2M iterations to still be well below subsecond - generally speaking - .5 a milli or less and sometimes and more often than not on smaller samples indeterminate. If you are trying to optimize powershell for subsecond runtimes, I'd argue you are using the wrong tooling methods and would even question using cmdlets. Plus you probably spend 3 seconds alone just typing ForEach-Object vs a single key! Nonetheless, the point here being that performance is largely inconsequential and people who run into perf issues due to aliases is an extremely small edge case. But I wouldn't swear them off any more than I would any other cmdlet that might have a faster dotnet counterpart.

$x=0
Measure-Command {(1..2000000) | foreach-object { $x++ } }

and

$x=0
Measure-Command {(1..2000000) | foreach-object { $x++ } }`
`

[rismoney]

I am not trying to put down anyone's point of view and apologize if I came across that way. I just want to change this, and get rid of this rule altogether, and the negative trickle down effect it is having across PSSA and other quality projects.

[michaeltlombardi]

Fallacy. Get-help % is no different than get-help foreach-object. If someone doesn't know what something means the help system is built for this.

The help system exists only in the prompt, not when reviewing scripts. In any case, leaving my code review to look up commands that are only unclear because they are aliases is not good UX. To be very clear, no one is arguing aliases should be avoided at the prompt, only in scripts and function definitions which are meant to be maintained and/or shared, which is what this practice guide points to.

You can override Where-Object by just defining a func -- in fact, it's easier to override the cmdlet name than the alias.

Which is more of an argument in favor of fully-qualified commands than using aliases. Functions are generally only a problem when clobbered but people can and do treat aliases as personally mutable shortcuts. Most people probably don't override the most common aliases (?, %, etc) but in a script or function declaration clarity and lack of ambiguity are very desirable.

As for a meaningful run-time performance difference between alias and not...

Your code example actually only executes ForEach-Object once in each test as it is called from the pipeline. I wish I had better on-hand data for you - aliases being slow was a subtopic at the PowerShell Summit, so someone does have better data than me - but I don't. One thing to keep in mind is that it's not just about performance - it's performance, safety, readability, and maintainability.

Aliases, given that context, are a losing proposition for scripts but totally fine at the prompt.

[rismoney]

The code example was an oversight in my hastiness to serve an example. Simply looping any alias vs a built in cmdlet should reveal a slight variation at very high usage.. I don't think anyone would argue this.

The help system exists only in the prompt, not when reviewing scripts.

The help system that is available to you, depends entirely on the IDE of your choosing. Every language has a learning curve.

people can and do treat aliases as personally mutable shortcuts

This is true, but the built-in's should be respected as Microsoft included them from original and have not removed them until core. How people treat them, is on them. If you choose to clobber an alias or a function, that is on you.

performance, safety, readability, and maintainability.

Lets review as I am not convinced that you gain any of these by avoiding aliases. I think that is what is being debated. There are many ways to do things in Powershell and I wouldn't make a commandment that says thou should only use dotnet functions over cmdlets because of perf. Both have their place.

Safety? I have already stated that aliases like functions can easily be overwritten with greater ease, thereby it's not safer.

function Get-ChildItem {write-host "hello"}  # this is immediate clobber
set-alias gci -Value "write-host" #fails without -Force -Option AllScope

Readability? This is hardly a true statement vs a matter of opinion.

• mount vs New-PSDrive? dir vs Get-ChildItem.
• verbosity comes at a cost. both in file size, readability from long statements/scripts
• you lose the idiomatic coolness of the language. I wish there were more things like ternaries, and shortcuts like % and ? and even parameter shortcuts like ea.
• if the end user learned the ridiculousness of the operators (-gt, -lt and -eq being greater than, less than, and equal), then they obviously don't need the coddling you propose when using select -eq select-object or where -eq where-object.
• when i see a cmdlet like Add-DnsServerResponseRateLimitingExceptionlist I want a barf bag

Maintainability - catchall... Aliases used in scripts are no harder to maintain than functions. Microsoft released broken changes in Core, where tons of cmdlets don't work and the same goes for aliases. A level of adaptation will be necessary to provide cross version compatibility which is independent of the context of alias usage. I mean they broke AD in core.

[rkeithhill]

I have already stated that aliases like functions can easily be overwritten with greater ease, thereby it's not safer.

And the way you fix that, as has been mentioned, is to use the module qualified name:

Microsoft.PowerShell.Management\Get-ChildItem

Whether you want to use module qualified names depends, I think, on how broadly you expect your module to be used. The more broadly, the more defensive you need to be IMO. I contribute to posh-git which is used by >100K users. We had a issue come in a few weeks back where it turned out the user had defined their own Get-Location function which broke the module. Using a module qualified name would have avoided that issue.

I just want to change this, and get rid of this rule altogether

This is where you lose me. I could maybe see that it shouldn't be on by default in which case I would enable it for my projects. Sorry, but I have spent too much time fixing bugs in modules due to the use of aliases. I value this rule.

[rkeithhill]

BTW early in the development of PSSA we postulated the need for different "PSSA profiles". That is, the amount of "linting" needed for a personal module is lower than one you'd publish to co-workers which is less than one you'd publish to the PSGallery. I could definitely understand how a set of rules tailored for publishing to the PSGallery would annoy folks that just want to publish a module for some co-workers to use.

This issue exists with C#'s FxCop / CodeAnalysis. There are a ton of rules - many of which are opt-in. Microsoft provides some high-level rule sets that you can pick from or you can create your own custom rule set:

[Jaykul]

Before I say anything else, I want to point out that contrary to what many people have asserted, using the "fully qualified name" of a command does not guarantee anything. All of these work:

Set-Content function:Microsoft.PowerShell.Management\Set-TimeZone { 
    Write-Host "Go Jump in a lake. UTC is the only way!"
}

Set-Alias Microsoft.PowerShell.Management\Set-TimeZone Write-Host

$source = (gcm pwsh.exe).Source                                          
Set-Content (Join-Path function: $source) { Write-Host $args -Fore Cyan }
${function:C:\Program Files\PowerShell\6.0.2\pwsh.exe} = { write-host $args -Foreground yellow }

Set-Alias $source write-host                                             
Set-Content (Join-Path alias: $source) Write-Host

You might consider this functionality to be a bug --it's certainly a frighteningly powerful feature-- and it's clearly very dangerous to do this, but it does work. Nothing is sacred...

[rkeithhill]

@Jaykul You just like to suck the joy out of everything. :-p

[dlwyatt]

That’s how Pester does mocking of module-qualified calls, incidentally.

On Apr 27, 2018, at 12:52 PM, Joel Bennett [email protected] wrote:

Before I say anything else, I want to point out that contrary to what many people have asserted, using the "fully qualified name" of a command does not guarantee anything. All of these work:

Set-Content function:Microsoft.PowerShell.Management\Set-TimeZone { Write-Host "Go Jump in a lake. UTC is the only way!" }

Set-Alias Microsoft.PowerShell.Management\Set-TimeZone Write-Host

$source = (gcm pwsh.exe).Source
Set-Content (Join-Path function: $source) { Write-Host $args -Fore Cyan } ${function:C:\Program Files\PowerShell\6.0.2\pwsh.exe} = { write-host $args -Foreground yellow }

Set-Alias $source write-host
Set-Content (Join-Path alias: $source) Write-Host You might consider this functionality to be a bug --it's certainly a frighteningly powerful feature-- and it's clearly very dangerous to do this, but it does work. Nothing is sacred...

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.

[Jaykul]

The problem with aliases is that there are many kinds of aliases:

1. The built-in "legacy aliases" like dir and mount and ls.

These map commands most people already know to their PowerShell equivalents. This includes aliases like foreach, sort, and where. The problem here is those aliases are dangerous now, because the PowerShell team has been removing them haphazardly from PowerShell Core, so many of these commands now fall through to (incompatible) native executables...

2. The built-in "native aliases" like gci and ndr

These are supposed to be intuitive: there is a defined mapping of (Get-)Verb -> AliasPrefix, and each noun gets a consistent alias. They are, however, less obvious than the full command, because you need a significant level of PowerShell experience to learn the default verb aliases and you still have to "just know" that dr is short for PSDrive and not DisasterRecover or whatever.

3. Module native aliases, like pumo and inmo

These are like the built-in native aliases, in that they are "intuitive" and automatically created (when you import a module). Most of Microsoft's modules export these (including PowerShellGet, from which my earlier examples come). These are, of course, even less obvious than the built-in aliases, because readers would need to be extremely familiar with a particular module to have encountered them. I, for one, had never noticed the pumo alias until today, and it's unlikely I'd have been able to figure it out: although I'm familiar with mo as the short form of the Module noun (I use ipmo all the time), pu is short for Push, not Publish (which is supposed to be pb)...

4. User created aliases

These are the aliases that are either (re)defined in your profile or within a script to help you type less. As a general rule, nobody but you would know them unless you were particularly clever with naming.

5. Automated hacking aliases

These are the aliases generated by tools like the Reflection module and others which are designed to mask built-in commands.

I think we can mostly agree that the first type of aliases I listed above have been relatively benign, and in many cases they do improve readability (Where instead of Where-Object, for instance).

However, even these are now problematic because they are being removed from PowerShell Core (i.e. sort and cd and all the bash utility aliases are no longer aliases in PowerShell on Linux).

[Jaykul]

This is a deliberately broad statement, so stick with me:

All types of aliases reduce readability

Readability is certainly a matter of perception.

What may seem readable to one person may not to another. Therefore, when we talk about readability we're striving to find the right balance between forcing people to learn a language's syntax and APIs (commands) and being able to intuit the right things about the code without full knowledge.

But there are still absolutes

I believe the three following facts are constants when you consider all the types of aliases that are out there (or even just the first three types):

1. Aliases are more terse, and less self-explanatory than full command names.
2. Aliases increase concept count by introducing more names for the same things.
3. Nobody knows all the aliases.

Did you know Remove-Item has six built-in aliases? Can you name them?

[Jaykul]

When we talk about readability we're not really talking about whether other PowerShell authors can figure it out by looking it up. We're asking whether someone who knows Go or C# can intuit what's going on...

I understand that for certain audiences, some aliases seem more readable than the full command names, but it actually depends very much on the context, and the audience.

rmdir is a very broadly recognized command. All your existing command-line users (regardless of their operating system of choice) will know it, and understand what it does. It's basically one of the best examples of readable aliases, so let's make it...

An example to prove the rule: rmdir

Take the following code:

rmdir $Profile

How many of your readers can reconcile their "knowledge" of what they think rmdir does, with the fact that it's actually an alias to a PowerShell command that works against folders, but also files? How many of your readers will leap to the incorrect conclusion that $Profile must point to my $Home directory, instead of a profile.ps1 script file?

On the other hand, do you think even a single one of those readers would be more confused by this:

Remove-Item $Profile

The fact is that Remove-Item is plain English. It's universally understood even by, say, Excel macro authors who've never used a shell -- even by non-technical people. Some people still may not know whether $Profile is a file or a folder, but at least nobody is being misled by their supposed knowledge of the alias.

So it's not really just a matter of opinion.

On top of that, no matter their backgrounds, because of Type 3 aliases, as I said before: nobody knows all the aliases.

There's no value in making people look up pumo to discover that the authors of the module incorrectly used pu and that mo is a module. If you write Publish-Module, anyone with a little familiarity with PowerShell will intuit what it does -- and if they can't, they can Google it (which is something they cannot do with "pumo" -- go on, try it, I'll wait).

[rismoney]

Agree 100% on context.

Rmdir to delete a profile is an intent obfuscation and i think everyone would agree a bad practice. Contrast that with del where there is no ambiguity and readbility is higher from all angles is what I am calling into question. That's not bad powershell where a rule should be written and a code violation raised.

For me the punctuation aliases in particular are the best and their counterparts shouldn't even be used. ? is awesome and should flourish in code bases everywhere. It's unfortunate the language took such a verbose take.

Based on the community I am surprised people even use pipelining. I mean why is | suddenly an easy lesson but & usage is out of bounds.

[Jaykul]

The point though, @rismoney, is that Remove-Item .\notes.txt is more readable: not just because linux uses rm, not del -- but because it's plain English. On top of that, it's more Googleable.

Even Linux command-line users don't use del (they use rm), so really, only someone who's used DOS would be guaranteed to recognize del .\notes.txt at all -- it's just not more readable.

As you know, my personal opinion is that a PSScriptAnalyzer rule about aliases should just be informational -- they are, as you say, not bad.

P.S. Also, rm and rmdir aren't aliases in PowerShell Core on Linux -- because they interfered with native commands and were removed.

[Jaykul]

To flip the script for a moment...

I don't think readability is the ultimate goal

Unless you're just blogging, and not writing code for a living.

The PowerShell Best Practices and Style Guide isn't about blogging. I mean, we want people to blog in such a way that they're supporting best practices, but the best practices aren't about blog readership, they're about the maintainability of production code.

Obviously maintaining code requires reading it, so readability is a part of this -- but in that sense we're concerned with coders who would be able to maintain the code in question. If you're working on a module or other "library code" and production code -- you don't need to worry about random blog readers who've never seen % and need to Get-Help del.

So although aliases reduce readability for people who are unfamiliar with PowerShell --and you definitely shouldn't use them on a blog post that's targeting beginner PowerShell users-- hopefully we can all agree that when working on production code we should be asking questions like:

1. How hard is it to maintain? a. How buggy is it? b. How easy it is to track down bugs? c. How hard is it to refactor?
2. How well does it work? a. How fast is it? b. How much RAM does it need?

At my company, when we've talked about readability I specifically say: "I don't care if a newbie can't read it. I want to know, can the average new hire DevOps engineer read it?" Someone with Ops or programming background, and at least intermediate PowerShell knowledge (or extensive knowledge in some other scripting language, so we can expect them to come up to speed in PowerShell fairly quickly).

Make sense?

Well, it turns out that the folks who are coming in without PowerShell knowledge (that is, .NET developers, Python DevOps experts, etc) can read our code if it's written with full commands. They can figure out what it does. But when we use aliases other than the Type One aliases I mentioned above (which are, as I mentioned, problematic for other reasons), they have problems. It takes longer for them to get it, longer to come up to speed.

So basically I just end up saying, look:

• the only cost of expanded aliases is a few extra characters in the file
• the expanded code is readable for a broader audience (although more verbose)
• we have tools that can "expand" aliases to their definitions
  • people who are reading my code can also use those tools themselves
  • (either way, authors don't actually need to type more)

So I just don't have a problem with aliases. One way, or the other. As long as you document your module requirements, and don't use aliases you made up yourself 😉

When it comes to idiomatic PowerShell ... When it comes to performant PowerShell ...

I'm less concerned with people using pumo and more concerned with getting them to use pipelines instead of loops, and writing functions with process blocks, that output objects (not hashtables), take their parameters ValueFromPipelineByPropertyName and have appropriate names or aliases on their parameters so they can match more pipeline input....

[midacts]

I think the mentality for using PowerShell at a live console and using aliases is one thing. This repo is about it more towards writing functions and modules, which is where you do want these structures and guidelines.

Aliases are easier for adhoc commands at the command prompt so you don't have to spend as much time typing commands. I don't think they should have a place in code that will be maintained.

[darkoperator]

Correct. The main purpose of the guideline is not for when using PS in the Console but when writing code to server as the name implies a recommended guideline based on the experience of several in the community about to how better format and structure code to make it easier to read, maintainable and less likely to introduce errors.

On May 16, 2018, at 10:21 PM, John McCarthy [email protected] wrote:

I think the mentality for using PowerShell at a live console and using aliases is one thing. This repo is about it more towards writing functions and modules, which is where you do want these structures and guidelines.

Aliases are easier for adhoc commands at the command prompt so you don't have to spend as much time typing commands. I don't think they should have a place in code that will be maintained.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/PoshCode/PowerShellPracticeAndStyle/issues/108#issuecomment-389723744, or mute the thread https://github.com/notifications/unsubscribe-auth/AAf0HsJu_UVi51QI7C9WCsxUQXHSYUyWks5tzN7HgaJpZM4TiIVr.

[rismoney]

I don't think they should have a place in code that will be maintained.

Thanks for your sharing your thoughts. Using your logic:

Aliases are easier for adhoc commands at the command prompt

They are easier to use in script as well.

This repo is about it more towards writing functions and modules, which is where you do want these structures and guidelines. ... I don't think they should have a place in code that will be maintained.

No substantiation.

[darkoperator]

in my previous work several of us maintained a module. Aliases at the start brought confusion when reading code (sometime we had to hunt for what an alias was, other times cmdlets with multiple alias had one used at one part of the code and another in another part) and in 1 case an alias was re-mapped by a dev causing errors that took a while to figure. Even when Aliases make code shorter you sacrifice readably and may introduce an error.

[Bill-Stewart]

Real use case: I remove the dir "compatibility alias" to use my own function that acts more like the dir that I've been typing for 25+ years. If some script or function comes along and assumes that dir is Get-ChildItem, then of course things will not work as expected. This has caused a number of confusing problems.

IMO, aliases are fine to shorten interactive commands but should be avoided in scripts (you are far more likely to run afoul of user-modified defaults like mine).

[rismoney]

Bill - Overriding default aliases is on you, not the script builder.

No different overriding cmdlets with your own functions. You are just on your own.