Call for Debates!

As the Scripting Games begin to wind down, I know that we've come across a number of divergent opinions, especially in the comments. "You shouldn't use .NET classes!" says one comment, "you should have done this with a .NET class" says another comment in the same entry. Fun. It's great to see those differences - but it'd be better to discuss them.

So I'm asking everyone in the Games: Go through your comments on all of your entries. Find comments that you disagree with - but that you could possibly see someone making an argument for (and that you'd perhaps argue against). Post those here as a comment, or email me (there's a contact form on the Site Info tab). I want to collect these, and start a series of discussions where we can, jointly, start to hammer out some patterns and practices that we, as a community, feel work well. Some of those may have exceptions (rules always do) - "never use a .NET class when there's a cmdlet that can do the same thing, but otherwise go nuts" is one example.

Fire away. For now, you don't need to put your argument for or against - I'm just collecting the topics that we've seen disagreement or differing opinions on. Discussion will follow!

The result of this will be a community-guided Best Practices ebook, which I'll assemble and we'll give away for free. I might even build that, initially, as a wiki, so that folks could contribute to it over time. Will see - that's a bit of extra software.

About the Author

Don Jones

Don Jones is a Windows PowerShell MVP, author of several Windows PowerShell books (and other IT books), Co-founder and President/CEO of PowerShell.org, PowerShell columnist for Microsoft TechNet Magazine, PowerShell educator, and designer/author of several Windows PowerShell courses (including Microsoft's). Power to the shell!

18 Comments

  1. It would be good to reach a consensus on the use of functions. Not so much the script vs function vs advanced function argument but more focused on modularizing your scripts and creating functions that only perform one task. While I received some positive feedback, I was quite surprised at the number of comments suggesting one function would have been a better approach.

    • I was surprised at the script vs. function feedback. Many of these tasks were obviously "single-focused" tasks. An audit report, provisioning a batch of VMs, etc - hardly a "function". When would I find myself applying many of these exact tasks generically? I fully support creating function libraries, modules if you will, that you auto-load via a profile on start so your session has at-hand all your custom needs, but they best either be every-day tasks or simple focused outcomes to justify that approach. For once a month tasks that generate a complete solution, are they not better suited as scripts? Called just as easy as a function - I fail to see the resultant 1 star feedback I saw so often.

      • I think your comment demonstrates that there is the need for debate here to establish best practice. That you received low scores for not using a function and that I received low scores for using too many suggests that there must be a middle ground to be found and trod.

        • I echoed those above. Just about every one of my submissions received a comment to the effect of "You should submit your stuff as a function, not a script" with absolutely no explanation why. I wholeheartedly disagree that this is the one and only correct approach and would love to debate it some more.

  2. To use alias or not to use alias? All of our mentors preach about when writing reusable scripts for others to use full syntax however during the games I see aliases used a lot and sometimes these scripts get voted way way up. I think it should be a demerit

  3. Technology requirements:
    One of the events required MS DHCP of which I do not have in my environment, An event prior to that benefited from having Hyper-V and the module for that technology. I also do not have this in my environment. For beginners at least I think the technology requirements should maybe be limited to things that are available to those with a more limited environment/budget

  4. Ok, here's a good one from Event 2. Should we change the value that was returned from the memory count? As we are GETting information should we change a byte value to a mega/gigabyte value or should the number be kept clean and unsullied for the pipe? Yes we can use the formatted value in the pipe too, but isn't the original number better?

  5. I’d like to see a discussion about handling default values. Also, does Write-Verbose –eq Write-Debug -or does Write-Verbose –eq comments -and who is the audience for Write-Verbose messages?

  6. I would like to see some discussion on using TRY/CATCH blocks vs using the built in error variables to handle errors, In the comments most people seemed to only go with TRY/CATCH but sometimes I think it is simpler to use $? to catch the error. And you don't have to force errors to be terminating.

  7. I'd like to see some discussion on what's appropriate for a workflow. I didn't participate in the last event, but did score some entries, and I marked that workflow solution down for needing a lot more system resources than it seemed like should have been needed to accomplish the event objective.

  8. I'm NOT complaining here, even if it looks like that!°
    I really feel that there has been a gap between your scoring guidelines and your score!

    I have to refer to my advanced event 1 here!
    http://scriptinggames.org/entrylist_.php?entryid=126

    ( It has been a bit experimental as it was the first entry in the games ... right! BUT it works in practice here and it does what it is supposed to do since some months )

    I will just cite three comments:
    -----------------
    (DonJ 1 star) I think there's a misunderstanding on $Error here. I wish you'd used more structured error handling instead of relying on the $Error collection, and clearing it. It's not a great practice. I like your logic, here, and your syntax is very careful, which I appreciate - I'm just not personally a fan of the error handling approach you've used. The use of -f is also not my favorite; why not make your code more readable by just putting variables and subexpressions right in quotes?

    (mjolinor 1 star) Error handling should incorporate flow control. If you get an error creating the target directory, don't proceed to try and move the files anyway. Use flow control statements (break/continue) to continue to the next folder.

    (RichardSiddaway 1 star) don't do this Mandatory=$False, HelpMessage= only works if mandatory=$true try-catch misused - try should be a single command with catch to get any exceptions
    ---------------
    I know what I did, because I wanted to make the script run though despite of any errors. Just let it do how much it could do and reprot what failed to work!

    The script does work in the sense of:
    http://scriptinggames.org/a93f37dcb5905d2f189b.pdf

    IMHO There is no functional failure in the script.

    If we read your own scoring guidelines:
    https://powershell.org/the-scripting-games/scoring-guidelines/ it says:

    1 star: We do not award one star just because some “best practices” were not followed. One star means the entry DOES NOT FUNCTION.

    And I received 1 star by Don, Richard and Mjolinor e.g.

    2 stars: You would never give this score just because an entry doesn’t observe all best practices.

    And all the script has been blamed for is: Not observing "best" practices!

    3 stars: This entry maybe misses some PowerShell conventions or items of consistency. There is obvious learning yet to be done – and your accompanying comment should help direct that learning.

    This is something I would aggree with!

    I feel, that you didn't follow your own scoring guidelines ...

    I did score one and two stars only to scripts that didn't do what has been required and I even gave three stars to some of them if the idea has been excellent but the final result didn't work exactly as required by the event description.

    Klaus.

    • Please remember that the scoring guidelines didn't exist during Event 1.

      And also, I'm really looking for general areas of debate, rather than specific complaints about specific scores on specific entries.

  9. Sorry Don,

    this is completely different from what I understood!

    I read: So I’m asking everyone in the Games: Go through your comments on all of your entries. Find comments that you disagree with – but that you could possibly see someone making an argument for (and that you’d perhaps argue against)

    --- a quote from .https://powershell.org/2013/06/10/call-for-debates/ ---

    Go through your comments: That's what I did!
    Find comments you disagree with: That's what I did!
    And that you'd perhaps argue against; That's what I did!

    You don't like my comment ... Accepted!
    But you should clarify what you are looking for!.
    Maybe I didn't get you right.

    I introduced my comment here, as no complaint!
    And I really am not complaining!
    I have no advantage from scoring any higher here, not at all!

    That the score guidelines didn't exits before event 1 is a fact.
    This way event 1 may have been scored differently ...

    Shouldn't we have had these guidelines before!?
    These are nearly the same as in each Scripting Games before!

    Klaus.

    • I was asking you to go through your comments and look for areas where you found disagreement over technique or approach, so that we could discuss those techniques or approaches. Not so that we could discuss your comments.

      For example, "in one of my entries, a few people said I should not use positional parameters. I disagree with them, so let's discuss the use of positional parameters or not."

      So in your particular case what would be useful is, "I had an entry where people said they did not like how I used $error to capture an error. This could be a useful discussion to have." At this stage, there's no point whatsoever in discussing the scores, or whether or not the scores were consistent with any guideline. I'm looking for PowerShell topics that we can discuss, not for another discussion on scoring. I'm sorry if I was not clear on that.

      So, to try and be clear, I am looking for PowerShell topics where people have different opinions on the "best way," so that we can have a community conversation about the pros and cons of different approaches. I don't want to discuss specific people or specific entries because that can create hurt feelings for some people.

      And yes, having scoring guidelines in place at the beginning would have been better. It's my fault I didn't do so.

  10. This is an interesting topic given that I was in the BOF session that Don and Glenn led (along with Ed Wilson) at TechEd.

    Event 5. (beginner track)
    This item was discussed in that session, but I think a more public airing of it is worthwhile. I saw the use of this Regular Expression, and it was suggested in a comment that I use the same: "\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}" Now I'm no pro on Regular Expressions, and I tend to avoid them where I can, but, as was pointed out in the TechEd session, that Regex doesn't validate an IP address, it validates 4 dot separated up-to-three-digit numbers. it would validate 999.888.77.666. But, of course that isn't an IP address. One could use the [ipaddress] type accelerator, or a more accurate regex. I chose the route of "find the column with 'c-ip' data in it. In the context of the event, there's a way to parse the header line from an IIS log. In my case, for example, I ran the code against not only the provided IIS logs, but against logs on my own IIS servers, and finding that there were no curve balls in the provided data, chose to be explicit about the header, even though that long collection of strings did feel a bit "dirty". Thing is, it works for a majority of IIS servers out there where the IIS log output has not been customized.

  11. Well 🙂
    I would love to see some more elaborated details on error handling!

    I'm not sure how to have complete error handling with Powershell considering some aspects like

    1. A script has to do as many work as it can
    2. If errors are raised, I would like to have a description of the error cause in a common language
    3. Other stuff is running my script. They don't know abot an Exception in line 321 position 123
    4. A log has to be created detailing each error in common language
    5. The script shouldn't break or stop

    This might be a topic for further discussions!
    Klaus.

  12. I'd like to see the best way to approach remote WMI calls. It appears from the winning entries in the games that some kind of uber-check function is desired for each attempted call to a remote machine. This uber-function would check:
    If there machine is online
    If the machine can be accessed using wsman and cmi cmdlets
    or do I have to use dcom and get-wmi....