(re)move detailed recommendations about validation attributes

[Jaykul]

trafficstars

https://github.com/PoshCode/PowerShellPracticeAndStyle/blob/master/Style%20Guide/English.md#when-using-advanced-functions-or-scripts-with-cmdletbinding-attribute-avoid-validating-parameters-in-the-body-of-the-script-when-possible-and-use---parameter-validation-attributes-instead

I think the style guide should just have the text of this headline and a link to Best Practices for using validation and TypeAdapter attributes on parameters.

When writing functions or scripts, avoid validating parameter values in the body of the script, and yse parameter validation attributes instead when possible (See Best Practices for Parameters).

Then we should ensure that in addition to linking to the help file on these parameter attributes, we provide more information than the help files do:

• Recommend (when to) use AllowNull, AllowEmptyString, AllowEmptyCollection and why.
• Recommend avoiding ValidatePattern
• Recommend always throw from ValidateScript to control the error message
• Any others?

Anyone have an objection to simplifying the style guide like that, or ideas about additional points for best practices?

[KirkMunro]

Since docs are open source, some of this could just be added to the docs, no? Unless you had something very verbose in mind, I wonder if it may be better to put recommendations on when to use AllowNull/AllowEmptyString/AllowEmptyCollection etc., plus why ValidatePattern shouldn't be used and why ValidateScript shoudl throw in the appropriate about file. I get that may be more detail than was intended in help, but I was imagining someone reading the help, then working with those, then later reading this additional documentation and wondering why they didn't just say that in the first place in the built-in (or downloadable since they're not really built-in anymore) docs.

*Kirk Munro * Poshoholic, Microsoft MVP Blog http://poshoholic.com/ | Twitter http://twitter.com/poshoholic | LinkedIn http://ca.linkedin.com/in/kirkmunro | GitHub http://github.com/KirkMunro | Facebook http://www.facebook.com/#%21/kirk.munro

Need a PowerShell SME for a project at work? Contact me http://poshoholic.com/contact-me/!

On Sun, May 31, 2015 at 1:26 AM, Joel Bennett [email protected] wrote:

https://github.com/PoshCode/PowerShellPracticeAndStyle/blob/master/Style%20Guide/English.md#when-using-advanced-functions-or-scripts-with-cmdletbinding-attribute-avoid-validating-parameters-in-the-body-of-the-script-when-possible-and-use---parameter-validation-attributes-instead

I think the style guide should just have the text of this headline and a link to Best Practices for using validation and TypeAdapter attributes on parameters.

When writing functions or scripts, avoid validating parameter values in the body of the script, and yse parameter validation attributes instead when possible (See Best Practices for Parameters).

Then we should ensure that in addition to linking to the help file on these parameter attributes, we provide more information than the help files do:

• Recommend (when to) use AllowNull, AllowEmptyString, AllowEmptyCollection and why.
• Recommend avoiding ValidatePattern
• Recommend always throw from ValidateScript to control the error message
• Any others?

Anyone have an objection to simplifying the style guide like that, or ideas about additional points for best practices?

— Reply to this email directly or view it on GitHub https://github.com/PoshCode/PowerShellPracticeAndStyle/issues/33.

[Jaykul]

There's a difference between documenting what an attribute does and how it works, and writing best practice suggestions for their use. I'm trying to draw a line between them and remove the docs stuff, but ...

If we can put best practices stuff into the about_* topics, and are comfortable doing so, maybe we don't need a separate set of documents, and we should just stick about_ on the front of all the section names I suggested, and push the whole book into the docs. Does that make sense? Is it a possibility?

Failing that, should we rename these all to about_* anyway, and ship them as a "BestPracticesDocuments" module?