DISCUSSION GUIDELINES

[Jaykul]

@darkoperator this is particularly for you and I as named and blamed stakeholders ;-)

Can we all agree on this (or something like it) as a statement of purpose to guide our discussions?

I realized this week that I've written a few things in the "must" and "require" and "forbid" style, and ended up in endless arguments -- I apologize to everyone for that, but I want to present something up front (in CONTRIBUTING.md) to help us all get the right tone (and to give people something to point at when they have to tell me I'm doing it wrong).

Purpose

PowerShell Best Practices are what you should usually do as a starting point. They are ways of writing, thinking, and designing which make it harder to get into trouble. The point of a Best Practice is to help the reader to fall into the pit of success:

The Pit of Success: in stark contrast to a summit, a peak, or a journey across a desert to find victory through many trials and surprises, we want our customers to simply fall into winning practices by using our platform and frameworks. To the extent that we make it easy to get into trouble we fail.

-- Rico Mariani, MS Research MindSwap Oct 2003.

Like English spelling and grammar rules, PowerShell programming best practices and style rules nearly always have exceptions, but we hope to document a baseline for code structure, command design, programming, formatting, and style which will help you to avoid common problems, and even help you write more reusable, readable code, because reusable code doesn't have to be rewritten, and readable code can be maintained.

Having said all of that, if you're having trouble getting something done because you're trying to avoid breaking a style or best practice rule, you've misunderstood the point: this document is pragmatic, rather than dogmatic.

Tone

One of the goals as we rewrite these documents is to make it easy to agree with them. As a result, we will avoid absolute language, and will encourage writing the proactive and positive guidelines rather than negative ones. Words like "always" and "never", "must" and "forbid" should be avoided when possible in favor of words like "usually", "normally", "should" and "avoid".

The points in the Best Practices documents and the Style Guide are referred to as practices and guidelines, not rules. That said, we should not shy away from making recommendations whenever they will make it easier to be successful, harder to fail, or easier for someone else to pick up the code later, but we should explain the rationale: and should particularly note when the reason is readability and maintainability, performance, or security, rather than just being a smoother path.

Knowing that there are cases where other patterns may be acceptable or even necessary is not a reason to exclude a practice that is correct most of the time. Rather, each practice or guideline should include the rationale, an example case, and when appropriate, counter examples and notable exceptions.

Organization

The guidelines will be divided into these sections:

• Style Guide
  • Code Layout and Formatting
  • Function Structure
  • Documentation and Commenting
  • Readability
  • Naming Conventions
• Best Practices
  • Naming Conventions
  • Building Reusable Tools
  • Output and Formatting
  • Error Handling
  • Performance
  • Language, Interop and .Net
  • Metadata, Versioning, and Packaging

Markdown documents on GitHub support linking within a document, but only to headers, so when editing, in addition to keeping practices and guidelines in the documents where they make sense, please use headlines for each guideline, and lower level headlines for rationale, examples, counter examples, and exceptions.

If you can't figure out where something should go, open an issue and we'll discuss it. If there are enough points which don't fit well in the current sections, we may open a new section.

Reminder:

The PowerShell Best Practices and Style Guide is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.

You are free to:

Share — copy and redistribute the material in any medium or format

Adapt — remix, transform, and build upon the material

The authors encourage you to redistribute this content as widely as possible, but require that you give credit to the primary authors below, and that you notify us on github of any improvements you make.

[rkeithhill]

practices and guidelines, not rules

This sounds good to me. That is one reason I liked the "Elements of Style" books. It's been a while but I don't remember them being too preachy. :-)