encourage instead of discourage alias #108
Comments
|
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 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 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. |
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. |
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 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 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
|
That's a very valid reason for discouraging them.
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. |
|
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.
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: and |
|
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. |
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.
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 (
Your code example actually only executes 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 that is available to you, depends entirely on the IDE of your choosing. Every language has a learning curve.
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.
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 AllScopeReadability? This is hardly a true statement vs a matter of opinion.
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. |
And the way you fix that, as has been mentioned, is to use the module qualified name: 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
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:
|
|
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-HostYou 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... |
|
@Jaykul You just like to suck the joy out of everything. :-p |
|
That’s how Pester does mocking of module-qualified calls, incidentally.
… On Apr 27, 2018, at 12:52 PM, Joel Bennett ***@***.***> 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.
|
|
The problem with aliases is that there are many kinds of aliases:
These map commands most people already know to their PowerShell equivalents. This includes aliases like
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
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
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.
These are the aliases generated by tools like the 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 ( However, even these are now problematic because they are being removed from PowerShell Core (i.e. |
|
This is a deliberately broad statement, so stick with me: All types of aliases reduce readabilityReadability 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 absolutesI 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):
Did you know |
|
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.
An example to prove the rule:
|
|
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 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 |
|
The point though, @rismoney, is that Even Linux command-line users don't use 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, |
|
To flip the script for a moment... I don't think readability is the ultimate goalUnless 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 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:
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:
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 ... I'm less concerned with people using |
|
I think the mentality for using PowerShell at a live console and using aliases is one thing. 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>.
|
Thanks for your sharing your thoughts. Using your logic:
They are easier to use in script as well.
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 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. |
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. |
That doesn't mean "the user should not change them." Otherwise, why have |
|
I think of writing PowerShell in two categories.
Aliases should be fine when using PowerShell interactively. 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. running some one-liners = 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. So unless you're a cruel, selfish sadistic **** , just make the code as plain english as possible and as readable as possible. |
|
cd > set-location Sorry, not sorry. |
Uh oh!
There was an error while loading. Please reload this page.
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 text was updated successfully, but these errors were encountered: