From 58dffb70dcd712a5f378f1fa146a03f18a106103 Mon Sep 17 00:00:00 2001 From: Stephen Owen Date: Tue, 2 Oct 2018 15:27:38 -0400 Subject: [PATCH 1/3] Added examples of Opening / closing braces Seemed like the life of this discussion issue has concluded, https://github.com/PoshCode/PowerShellPracticeAndStyle/issues/24, so lets include the agreed upon examples inside the docs :) --- Style-Guide/Code-Layout-and-Formatting.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/Style-Guide/Code-Layout-and-Formatting.md b/Style-Guide/Code-Layout-and-Formatting.md index 51644b2..d3e5fbd 100644 --- a/Style-Guide/Code-Layout-and-Formatting.md +++ b/Style-Guide/Code-Layout-and-Formatting.md @@ -82,12 +82,21 @@ end{} You can always delete or ignore one of the blocks (or add the `begin` block), add parameters and so on, but you should avoid writing scripts or functions without CmdletBinding, and you should always at least _consider_ making it take pipeline input. #### Open braces on the same line -Code folding is nicer in many editors. -(TODO: This is in discussion in [#24](https://github.com/PoshCode/PowerShellPracticeAndStyle/issues/24)) - +Code folding is nicer in many editors when a scriptblock is placed on the end of the same line, as in this example. + +```` +function Get-Noun { + end { + if($Wide) { + Get-Command | Sort-Object Noun -Unique | Format-Wide Noun + } else { + Get-Command | Sort-Object Noun -Unique | Select-Object -Expand Noun + } + } +} +```` #### Closing braces always on their own line -Because that's how they're supposed to be! -(TODO: This is in discussion in [#24](https://github.com/PoshCode/PowerShellPracticeAndStyle/issues/24)) +Note the above example again, community guidelines recommend placing your closing braces on their own line. This practice makes it easier to pair up matching opening and closing braces when looking to see where a particular scriptblock ends. #### Prefer: param() begin, process, end That's the order PowerShell will execute it in From 329e3cd3ba74319f11ee7ae131233f77e48681d2 Mon Sep 17 00:00:00 2001 From: Stephen Owen Date: Wed, 3 Oct 2018 10:44:58 -0400 Subject: [PATCH 2/3] pr feedback --- Style-Guide/Code-Layout-and-Formatting.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Style-Guide/Code-Layout-and-Formatting.md b/Style-Guide/Code-Layout-and-Formatting.md index d3e5fbd..8fbea1d 100644 --- a/Style-Guide/Code-Layout-and-Formatting.md +++ b/Style-Guide/Code-Layout-and-Formatting.md @@ -81,13 +81,15 @@ end{} You can always delete or ignore one of the blocks (or add the `begin` block), add parameters and so on, but you should avoid writing scripts or functions without CmdletBinding, and you should always at least _consider_ making it take pipeline input. -#### Open braces on the same line +#### Follow the one-true-brace style. +Open braces always go on the same line + Code folding is nicer in many editors when a scriptblock is placed on the end of the same line, as in this example. ```` function Get-Noun { end { - if($Wide) { + if ($Wide) { Get-Command | Sort-Object Noun -Unique | Format-Wide Noun } else { Get-Command | Sort-Object Noun -Unique | Select-Object -Expand Noun From c0b62840712ffe176cd654cfc6056ce4dbc365d0 Mon Sep 17 00:00:00 2001 From: Stephen Owen Date: Wed, 3 Oct 2018 10:51:23 -0400 Subject: [PATCH 3/3] Implementing JayKul's feedback --- Style-Guide/Code-Layout-and-Formatting.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/Style-Guide/Code-Layout-and-Formatting.md b/Style-Guide/Code-Layout-and-Formatting.md index 8fbea1d..9ba54c2 100644 --- a/Style-Guide/Code-Layout-and-Formatting.md +++ b/Style-Guide/Code-Layout-and-Formatting.md @@ -81,8 +81,10 @@ end{} You can always delete or ignore one of the blocks (or add the `begin` block), add parameters and so on, but you should avoid writing scripts or functions without CmdletBinding, and you should always at least _consider_ making it take pipeline input. -#### Follow the one-true-brace style. -Open braces always go on the same line +#### Brace yourself: Follow the one-true-brace style. +Open braces always go on the same line. + +This style really won in the PowerShell community partly because the style is one of two used in C languages --it's a variant of the K&R (Kernighan and Ritchie) style from their book The C Programming Language-- but also because for the first few years of PowerShell's existence, this was the only style that could be typed at the command line. Code folding is nicer in many editors when a scriptblock is placed on the end of the same line, as in this example. @@ -97,8 +99,10 @@ function Get-Noun { } } ```` -#### Closing braces always on their own line -Note the above example again, community guidelines recommend placing your closing braces on their own line. This practice makes it easier to pair up matching opening and closing braces when looking to see where a particular scriptblock ends. +#### Closing braces start a new line +Note the above example again, community guidelines recommend following the ['One-True-Brace-Style'](https://www.wikiwand.com/en/Indentation_style#/K&R_style) placing your closing braces on their own line. This practice makes it easier to pair up matching opening and closing braces when looking to see where a particular scriptblock ends, and allows one to insert new lines of code between any two lines. + +To reiterate, these are community best practices, and a lot of the code you'll find online from community leaders will follow these guidelines. That doesn't mean that those who follow different style guidelines are wrong. You may be the one to set the course for your company or your own project; we simply offer this guidance for your consideration. #### Prefer: param() begin, process, end That's the order PowerShell will execute it in