-
Notifications
You must be signed in to change notification settings - Fork 289
This issue was moved to a discussion.
You can continue the conversation there. Go to discussion →
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
There is no One True Brace Style #81
Comments
Allman styleThe Allman style is named after Eric Allman, who wrote many of the BSD utilities. It puts braces on their own lines, indented to the same level as the control statement, and indents statements within the braces. This style is the Visual Studio default indenting style for C# and is the standard for dotnet, PowerShell, asp.net, and basically, all Microsoft C# projects. enum Color
{
Black,
White
}
function Test-Code
{
[CmdletBinding()]
param
(
[int]$ParameterOne
)
end
{
if(10 -gt $ParameterOne)
{
"Greater"
}
else
{
"Lesser"
}
}
} In PowerShell, braces sometimes are not for logic or flow-control, but function more like quotes: enclosing a script-block that you assign to a variable or pass as an argument. In those cases, the brace must be on the same line with the variable or command it's being passed to, so it will look wrong among Allman style indenting. Built-in commands like |
K&R (One True Brace Style variant)K&R is named for Kernighan and Ritchie, who used it in their book The C Programming Language. According to Wikipedia it originated in Kernighan and Plauger's The Elements of Programming Style and Software Tools. It puts braces on the same line as control statements. The One True Brace Style is the K&R style with every braceable statement always having the brace on the end of the line. The original K&R puts braces for functions on a new line, and gave you the option to leave off braces for one-line statement blocks (which you cannot do in PowerShell). enum Color {
Black,
White
}
function Test-Code {
[CmdletBinding()]
param(
[int]$ParameterOne
)
end {
if (10 -gt $ParameterOne) {
"Greater"
} else {
"Lesser"
}
}
} The primary argument for OTBS is practical: when code is written following this style, new lines of code can be inserted between any two lines with no risk of accidentally breaking the code by separating braces from their statement blocks. In PowerShell, this style gained many adherents early on, because prior to the arrival of the ISE in PowerShell 3 and later the PSReadLine module, it simply wasn't possible to put most braces on a new line when typing them into the console, and this was the only place you could type that knew anything about the language! The console expected a single line of PowerShell, and would produce errors if, for instance, you didn't put a |
StroustrupNamed after Bjarne Stroustrup, who created it while writing his Programming: Principles and Practice using C++ and The C++ Programming Language, this style is a long time favorite of those who learned C++ as their first language. It is essentially a variant on K&R discussed earlier, with some variations: "else" blocks are placed on a new line. Unlike the OTBS variation, it follows K&R's suggestion that although the opening brace for a class and a struct are not on a separate line, for a function it is. It also allows skipping the braces for single line statements, but that's not allowed by PowerShell's parser. enum Color {
Black,
White
}
function Test-Code
{
[CmdletBinding()]
param(
[int]$ParameterOne
)
end {
if(10 -gt $ParameterOne) {
"Greater"
}
else {
"Lesser"
}
}
} The changes Stroustrup makes means that this style looses the "insert a line anywhere" feature of OTBS, and looks somewhat like a cross between Allman and OTBS. |
It appears to me that PowerShell advocates of "Stroustrup style" don't actually care for anything he says except having the |
P.S. As a side note (and I will brook no discussion on this): spaces won. In this guide, an indentation level is 4 spaces. For thoroughness, I reviewed C, C++, BSD, Linux kernel, Google's JavaGuide and the dotnet, asp.net, and PowerShell guides -- they all use spaces, except the Linux Kernel. Google's Java guide uses 2 spaces. All of the others use 4 spaces. The kernel coding style guide, being written by a dictator who still codes in a terminal, not only requires tabs, it specifies tabs as 8 characters, limits line length to 80 characters, and considers anything over 3 levels of indent to be a design flaw. It also refers to K&R as prophets, and to those who disagree with K&R as heretics, and considers the violation of naming conventions a "shooting offense" ... |
P.P.S. The Linux Kernel advocates for the pure K&R indentation style, with neither the OTBS variation forced upon PowerShell in the early days, nor Stroustrup's lonely else, in defense of this difference between function braces and everything else, they write:
This was the best defense I found for that oddity of K&R's bracing style. Obviously in the C# and PowerShell world, K&R are not considered "prophets" and the Allman style prevails -- but additionally, it's worth pointing out that functions are not special in PowerShell: they can be nested. This may be sufficient reason for the PowerShell variant of Stroustrup's variant to choose to treat the braces for functions the same as other braces (putting them at the end of the line), but when combined with the prohibition on leaving braces off, it certainly argues that this PowerShell-Stroustrup style is no longer the C++ standard style, but something invented by PowerShell programmers.... |
Even though I had no idea what is OTBS I mostly use it in my code. I prefer it cause it is neat. Since most PowerShell function are really simple and short, scrolling tons of braces doesn't seem convenient. |
I use OTBS with Stroustrup else. I believe i started my programming/scripting foray with PHP so it may have started there but I carried it in to VBscript and Powershell. Allman style is a waste of space, literally rather than figuratively, and OTBS with else on the same line is just unnecessarily confusing compared to the rest of the script. That's my two pence...🇬🇧 |
I use Allman style when writing code for clients and sometimes for colleagues. I use a variant on Allman when I don't care about anyone else. |
4 spaces is 2 too many. |
I made some minor code formatting changes to fit with the code formatting in use throughout so far. I use the [PoshCode/PowerShellPracticeAndStyle#81 with Stroustrup else).
PowerShell doesn't use Allman style. It uses C#/.NET style (which is Allman style). So one degree of indirection. PowerShell is conventionally indented with 4 spaces because Windows. I came from a Unix background (East coast, Murray Hill by way of University of Wateroo) where we used OTBS and tabs. With tabs, you could set your editor to display 2, 4, 8 or however many spaces you wanted. Much less cursoring about too. |
As Mr. Bennett noted, we can't use C#/.NET/Allman/Whitesmiths with cmdlets that use a scriptblock, as in:
... due to the fact that the cmdlet needs the scriptblock as its next token (we can use My current preference is OTBS without the "cuddled else" (the "cuddled else" looks inconsistent IMO), with two spaces for indentation. (I don't understand why using more than 2 spaces is necessary. Perhaps someone could explain?) |
@Bill-Stewart 2 space indentation is something I've seen in serialized languages (such as XML), but no where else. I suspect because the code is less readable with everything scrunched together and a lack of whitespace. |
I would say that "scrunched together" is a matter of opinion...I think 2-space indentation is actually more readable than 4-space. 3-space indentation is also pretty readable to me, but 4 spaces seems excessive. |
While I generally prefer AllMan for "proper" programming (C#, C++ et. al.) I use K&R (One True Brace Style variant) for PS because I found it's a neater compromise for how the powershell interpreter works without having to provide it hints ( ` ) and because I personally dislike mixing styles for different constructs (class, functions, conditionals vs cmdlets etc). function MyFunkyCode {
DoGreatThings
}
Invoke-Something -ScriptBlock {
MyFunkyCode
}
MyHash = @{
a = 'b'
}
# Also consistent with arrays
MyArray = @(
'a'
'b'
) I'm open on 2 vs 4 paces. Mostly I prefer 4, because if 4 starts looking "too big" it generally means I need to start refactoring. |
so it sounds like the only agreement here, is that people disagree. Perhaps instead of community agreement, it should be left up to the project to denote the style. Items like the PSSA, if it were to validate spaces for example, should have a tunable convention. Me personally, I want nothing to do with 4 spaces or tabs, Allman, Strousup, but rather |
@rismoney I think there are some advantages to languages having a "canonical" style. If anything, it helps when folks read books or look at docs if there is a semblance of a consistent style for the language. That said, if any individual wants to do things their way on their own project, I say knock yourself out. And the tools should support you i.e. they should be flexible enough so you can configure them to verify your chosen style. In this case, I have just two bits of advice. First, be self-consistent. It drives my OCD bonkers when looking at someone's code and they can't seem to make up their mind if they're using Second, when you are contributing to someone else's project - for the love of Jeebus - follow their project's coding style. It's like going into someone else's house - follow their house rules - if they want you to take your shoes off before proceeding, you do that. It's common courtesy. Now sometimes that can be hard if they're not self-consistent. So pick the style that's consistent with the majority of the existing script. Also, the last thing a maintainer wants to see is a one-line bug fix in a file that you've completely reformatted to your own style preferences. At the very least, keep semantic changes and style changes in separate PRs. |
I agree with @rkeithhill . The first rule of good style is to follow the existing style in the file/project. For new files you follow the company/team/project guidelines if you have them, if not use either the recommended style for the language or your preferred style. If this guide were to recommend a style, I'd phrase it along the lines of "If you do not yet have a preferred style for PowerShell, we recommend starting with K&R OTBS, as it's the most common style and will be the one you encounter most often." |
I started undergrad work in 1995. K&R style guides were clutched as if they were the last copies of a lost religious text. Over time, the code I wrote fell in line with OTBS by coincidence. Largely, I paid close attention to some functions/modules/etc. written by folks whose names would come up often, be it book credits, large bodies of work and, ultimately, time in the game. Thanks for the knowledge posted here and the time everyone has put into helping us blokes get it as good as we can. The Mrs has a MFA, and she is definitely the artsy type. I call good coding a science. She says it's a form of art. I suppose it is, if you're into that postmodern stuff. Thinking about it both ways has been a boost, though! |
Pasting the following into powershell breaks, requiring modification before testing a block of code in the console: if (10 -gt $ParameterOne) {
"Greater"
}
else {
"Lesser"
} This alone is reason for disregarding Allman and Stroustrup. Notably, modification to K&R is required for the console. This is the case for PowerShell 5.1, 6, and 7-preview. |
Not sure what you mean; that code works fine (syntax-wise) when posted into a console. |
* use OTBS code formatting PoshCode/PowerShellPracticeAndStyle#81 (comment) * auto format & save on powershell
That indeed works well on Windows, @rkeithhill and @Bill-Stewart but not on Unix-like platforms, as of PSReadLine v2.0-rc1 - see PowerShell/PSReadLine#1261 |
That's not actually true @mklement0, PSReadLine's paste functionality works the same on Linux, unless your terminal intercepts the Ctrl+V hotkey (in which case, change it to Ctrl+Shift+V in PSReadLine 😉) |
You shouldn't have to redefine or define alternativse to whatever your terminal's paste-from-clipboard shortcut is - or any of its other, menu-based paste methods (which you probably can't redefine). Similarly, right-clicking on Windows should work just like Ctrl+V pasting. That is, while a given terminal may paste by simulating keystrokes, which is outside of PSReadLine's immediate control, a fix is - fortunately - still planned: PowerShell/PSReadLine#579 To quote @lzybkr from that issue (PowerShell/PSReadLine#579 (comment)):
And said heuristic approach is fleshed out more in PowerShell/PSReadLine#579 (comment) |
The bottom line is:
|
Shift+Enter also depends on the terminal, because VT doesn't send "Shift" as a key press, and there's no capital Enter 😉 (it doesn't even work in Windows Terminal) |
That's good to know, @Jaykul (I realized I had gone down that rabbit hole before, and I've just summarized what - limited - set of chords are actually usable with Not being able to use the same key chord on all platforms is an additional annoyance, but I think the fundamental (but unavoidable) problem is having to remember that and when to add a line explicitly using a different key chord is necessary, which makes |
At the end of the day, most people don't switch operating systems or terminals very often -- so switching and needing to change your configuration may be annoying, but it isn't common 😉 Figure out what your most restrictive platform can handle (pwsh on Unix over VT, from inside bash) and configure something that works -- then use it everywhere. Regardless, I think whether the default hotkeys for PSReadLine work (or not) is basically irrelevant to the community's choice about code formatting -- people who are trying to use PSReadLine to justify choosing something other than OTBS obviously don't care about other hosts and experiences without PSReadLine 😉 |
This issue was moved to a discussion.
You can continue the conversation there. Go to discussion →
There are many brace and indent styles in programming, but in the PowerShell community, there are essentially three:
I've briefly given an example and explained the rationale for each below
Feel free to comment, but please vote for your favorite by using the 👍
And of course, if there's one you can't stand, feel free to give it a 👎
The text was updated successfully, but these errors were encountered: