encourage instead of discourage alias

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.

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 <notifications@github.com> 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 GitHub<#108>, or mute the thread<https://github.com/notifications/unsubscribe-auth/AQDqFk3y74jwnPP7ag66FWFK2rFCQYdmks5tr2VwgaJpZM4TiIVr>.

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

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.

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

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.

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.

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.

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

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.

@pauby

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

PowerShell/PowerShell#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 - majkinetor/au#19 . I'm not surprised @pauby, since you created majkinetor/au#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++ } }`
`

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.

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.

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.

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.

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:

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:

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?
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....

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.

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 ***@***.***> 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 <#108 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAf0HsJu_UVi51QI7C9WCsxUQXHSYUyWks5tzN7HgaJpZM4TiIVr>.

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.

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.

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).

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.

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

Nope; sorry. I would have to disagree very strongly with that. No code should assume aliases are set to specific commands. Aliases are under user control for a reason.

Built in aliases have been present in powershell since inception. If you break the built in functionality it's on you. I'd agree with you, but then we'd both be wrong.

Built in aliases have been present in powershell since inception.

That doesn't mean "the user should not change them." Otherwise, why have Set-Alias that can modify default aliases? Sorry; no. Aliases are user-accessible and should not be assumed to be immutable.

I think of writing PowerShell in two categories.

Interactive console
Writing code

Aliases should be fine when using PowerShell interactively.
I do not think they should be using in code. Code should be more formal and easier to read when writing it for code.

Similar to trying to write something in the shortest one liner possible. This should be reserved for the console only.

I think of writing PowerShell in two categories.

Interactive console

Writing code

Aliases should be fine when using PowerShell interactively.
I do not think they should be using in code. Code should be more formal and easier to read when writing it for code.

Similar to trying to write something in the shortest one liner possible. This should be reserved for the console only.

agree, alias only in the user profile for the direct console interaction.

Makes perfect sense in that context

…

Sent from my iPhone

On Sep 2, 2019, at 1:16 PM, Xiang ZHU ***@***.***> wrote: I think of writing PowerShell in two categories. Interactive console Writing code Aliases should be fine when using PowerShell interactively. I do not think they should be using in code. Code should be more formal and easier to read when writing it for code. Similar to trying to write something in the shortest one liner possible. This should be reserved for the console only. agree, alias only in the user profile for the direct console interaction. — You are receiving this because you commented. Reply to this email directly, view it on GitHub, or mute the thread.

I'll leave my two cents here for what its worth.
I have the same opinion about this as I have about documentation:
ITS NOT ABOUT YOU!!

running some one-liners = use whatever you like, knock yourself out.
putting together the skeleton of a new production script and just getting the guts together to confirm it'll do what you want = use whatever you like, knock yourself out.

Writing a Production script/module = ITS NOT ABOUT YOU!!

You could die the day after that script goes live, car crash driving to work, heart attack, whatever.
Some poor bast**d then has to pick up that script and figure out just what the hell you wrote.

So unless you're a cruel, selfish sadistic **** , just make the code as plain english as possible and as readable as possible.
The same applies to documentation. you dont document your systems to make YOUR life easier, you make it easier for the people around you and the poor sods who take your position after you when you decide to **** off somewhere else and leave no documentation.....

cd > set-location

Sorry, not sorry.

Navigation Menu

Repository navigation

encourage instead of discourage alias #108

8 remaining items

I don't think readability is the ultimate goal

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

encourage instead of discourage alias #108

Description

Activity

ChrisLGardner commented on Apr 24, 2018

lipkau commented on Apr 24, 2018

rismoney commented on Apr 24, 2018

lipkau commented on Apr 24, 2018

michaeltlombardi commented on Apr 24, 2018

pauby commented on Apr 24, 2018

rismoney commented on Apr 24, 2018

OraDotNetDev commented on Apr 25, 2018

pauby commented on Apr 25, 2018

rismoney commented on Apr 25, 2018

rismoney commented on Apr 25, 2018

michaeltlombardi commented on Apr 26, 2018

rismoney commented on Apr 26, 2018

rkeithhill commented on Apr 26, 2018

rkeithhill commented on Apr 26, 2018

8 remaining items

Jaykul commented on Apr 28, 2018

I don't think readability is the ultimate goal

midacts commented on May 17, 2018

darkoperator commented on May 17, 2018

rismoney commented on May 17, 2018

darkoperator commented on May 17, 2018

Bill-Stewart commented on Aug 27, 2019

rismoney commented on Aug 27, 2019

Bill-Stewart commented on Aug 27, 2019

rismoney commented on Aug 27, 2019

Bill-Stewart commented on Aug 27, 2019

midacts commented on Sep 2, 2019

copdips commented on Sep 2, 2019

darkoperator commented on Sep 2, 2019

Guyver1wales commented on Dec 18, 2019

rismoney commented on Dec 18, 2019

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions