2012 Scripting Games Judging Criteria Revealed

2012 Scripting Games Judging Criteria Revealed

  • Comments 13
  • Likes

Summary: Microsoft Scripting Guy, Ed Wilson, discusses the judging criteria for the 2012 Windows PowerShell Scripting Games.

 2012 Scripting Games badge

Microsoft Scripting Guy, Ed Wilson, is here. Today is the day that I reveal the judging criteria for the 2012 Windows PowerShell Scripting Games. In many respects, good Windows PowerShell code is good Windows PowerShell code. So the judging criteria this year reflects this fact.

General criteria for good Windows PowerShell scripts

  1. You should be able to read and understand your script. If you cannot read and understand your script, you will never be able to effectively modify it or troubleshoot it.
  2. Use native Windows PowerShell cmdlets and capabilities unless a clear cut reason dictates otherwise.
  3. Use comment-based Help.
  4. Format your script to facilitate reading and understanding of the script.
    • Line up related items, and indent subordinate or dependent items.
    • Use comments, but avoid in-line comments. Instead, place comments on their own line ahead of the code to which the comment refers.
    • Avoid aliases in scripts.
    • Write your code so that it can be read without requiring horizontal scrolling. To do this, consider using variables and natural line breaks (such as the pipe (|) character). Avoid line continuation marks if at all possible, but not at the expense of creating really long lines of code.
    • Leave the pipeline character on the right side of the code.
    • Put at least one space between commands.
    • Place individual commands on individual lines unless the command is exceedingly short and separating the commands would hinder readability.
  5. Keep the integrity of an object as long as possible. Avoid using Write-Host.
  6. Write reusable, self-contained functions.
    • Functions should return objects.
    • Use Verb-Noun naming for functions.
    • Prefer the singular for nouns in function names.
    • Functions should accept piped input if it makes sense to the application.
    • Do not call a function like a method.

Specific grading criteria

All scripts are graded on a five-point scale.

  • One point is awarded for a submission. All scripts will receive at least one point.
  • One point is awarded if the script runs and meets the minimum requirements of the scenario.
    Therefore, a submitted script that runs and meets the requirements of the scenario will receive two points. If a script runs, but DOES NOT meet the requirements it will only receive 1 point, which is the same score as a script that attempts to meet the requirements of the scenario but does not work.
  • The other three points depend on the scenario.
    In most cases, there will be four or five specific criteria that a script must meet. To receive all five points, a script must meet all of these criteria. If a script omits one criterion, one point is taken from the total of five. Therefore, a script would receive four points if it met all but one of the criteria and it worked properly.
    If a scenario only lists two criteria, and the script worked properly and met both of the criteria, the script would receive five points. A script that only met one of the criteria, would receive only four points.
    However, there is an evaluation process on the part of the judge—a judge may decide that a script is only worth 2 or 3 points instead of four or five.

Script judging

It is the intention that every script will be graded by at least two judges, and that a script will receive at least one comment from a judge. This is not a contract, however, and some scripts may only receive one grade and no comments. It all depends on how busy the judges are, and on the number of scripts submitted for a particular event.

If the last two years are any indication, the first scripts submitted for the first event will in all likelihood be graded 10 or 12 times because the judges are anxious to get on with the 2012 Scripting Games. As the events progress, it is also possible that some scripts will continue to be graded many times, and others will receive only a few. This is because all judges will not be able to grade all scripts all the time (although it is possible that some judges may be able to do so).

Please keep in mind that we will run reports that will point out which scripts need grading and need comments. All the judges have full time jobs, and all are uncompensated volunteers. The real point of the Scripting Games is to learn scripting. For more background about the Scripting Games, see the following posts:

The 2012 Scripting Games are going to be great. They will be fun, exciting, and a tremendous learning opportunity. Maybe you will win and get a free pass to TechEd, a conversation with Jeffrey Snover, and a chance to write a guest blog post for the Hey, Scripting Guy! Blog. If so WOO HOO! But if not, keep plugging away. Microsoft MVP, Bartek Bielawski, did not win the Scripting Games the first time out either.

I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.

Ed Wilson, Microsoft Scripting Guy

Your comment has been posted.   Close
Thank you, your comment requires moderation so it may take a while to appear.   Close
Leave a Comment
  • Hi Ed,

    nothing to comment here, except: "Let the games begin!" :-)))

    And one thing in advance: Thanks to you, the sponsors, the judges and all the other people envolved in making them possible ...

    And of course we shouldn't forget Microsoft and the Powershell team --- No Powershell scripting without them!

    Klaus (Schulte)

  • It will be fun to learn and see what techniques people use to accomplish the same goal.

    However, submitting scripts was very frustrating last year due to terribly inconsistent judging. Also, I never received my prize from the random drawing either.

  • Can you clarify what is meant by "do not call a function like a method"?

  • @K_Schulte indeed, let the games begin. Thanks to the sponsors, judges, and others. It will be awesome.

    @gaw you should send email to Scripter if you did not get your random drawing prize ... (too late now, but for this year please do not hessitate to speak up). Also keep in mind that the email listed when you sign up for the games is the email used for sending the prizes. We have the judging criteria, but with 30 different judges, each judge applies things differently. The main thing is to learn, and to see how different people approach things.

    @Jason myfunction(inputstuff) is called like a method. myfunction -myparam inputstuff is not. Or myfunction inputstuff is not called like a method. The first way, myfunction(inputstuff) works, but causes complications with more than one parameter, and is not allowed when using Set-Strictmode.

  • This might show my limited knowledge of powershell, but why avoid Write-Host ?

  • Dave,

    I think what Ed means here is that older scripting languages only had message/text output. While PowerShell can do this sort of output, with Write-Host, it is preferrable to output a useable object. This allows you to capture the object(s) in a variable if you so chose and manipulate it further. So rather than Get-Process printing out a complicated series of text lines in the shape of a table, you can actually output the data as an object with properties, capture that data in a variable, and use it for whatever. In this case it might be stopping leaking processes. Additionally if you don't wish or need to manipulate the outputted data, it'll present itself to the shell as text in a succinct and organized way.

    Jeremy

  • @All

    Write-Host does not produce usable text output.  It produces informational text output that is not normally available to capture or to further processing.  

    The use of Write-Host to satisfy output requirements should always be avoided in all PowerSHell scripts because it is unusable for anything but simple informational display about something such as a step in the script.  

    In my opinion this can be better served by using Write-Verbose because it can be enabled and disabled as needed..

  • These guidelines sound like a really good starting point (almost a style guide).  I do think that a little more clarity could be added in #5 (Keep the integrity of an object as long as possible. Avoid using Write-Host.)  There have already been some comments about how write-host doesn't produce "consumable" output and I agree that it's preferable to use write-output so that objects are emitted.  But the phrase "keep the integrity of an object" is probably not conveying what it needs to.

  • Under General Criteria #2, I have a question.

    Will the Windows 2008 R2 modules be allowed or do we have to go old school.  For example, will it be assumed that you have imported the ActiveDirectory module, will you have to call it within the script or will it even be allowed?  On that note will we be assuming a Windows 7/2008 R2 host or will we also have to accomodate running on an XP host.

  • @Robert It will not be assumed that you have imported a specific module. Therefore, if your solution uses a module you should import it. In addition, you should ensure that the module will be available, if it is not a general part of the OS. Keep in mind that your submission could be graded by any one of 30 judges. These judges are simply going to run the script in their test environment. They are not going to spend time troubleshooting your entry, and fiddle around with their test environment, in attempts to get your script to work. This is actually a really good exercise, a script should simply work. In the scenarios, I will state if you are running in a domain, a workgroup, or what forest level your AD DS is at. This will let you know if you can use the AD cmdlets, or something else. The exception to this would be if you decided to use the beta of Windows 8 client, or PowerShell 3.0.

  • @Mike There is always a challenge between brevity, clarity, and verbosity. You are correct, I could have probably phrased it better. My intention with this guideline was to avoid what we see so much of in many VBScript types of scripts, i.e. the scripter spends great amounts of time formatting the output just so. In fact, we see a 100 line script that really is one line of code that obtains the data, and 99 lines of script that sorts, selects, arranges, and morphs the output into a single purpose, non-reusable output. Then the next time the data is addressed, it requires another 100 line script to do essentially the same thing, but in a different manner. The bottom line is that functions should return objects so that the consumer can format the data in anyway they wish. Adding lots of write-host or format-* types of commands to your script doom it to single use. If this is a requirement, then put the data gathering portion into a re-usable function, and then write a quick script to format the output the way you require.

  • @Jason The following calls a method:

    $wsh = New-Object -ComObject wscript.shell

    $wsh.Popup("hi")

    The following creates a function, and then calls it like a method:

    function test {Param($a) write-host $a}

    test("hi")

    The following illustrates two ways to call the function, NOT like a method:

    test -a "hi"

    test "hi"

    Calling a function like a method is possibly error prone, and is not considered good PowerShell form. It is one of the conditions checked Set-Strictmode -version 2.0 is enabled.

  • Hi Ed,

    I'm quite sad because my script received 3.5 points while it's exactly the same with the one on the top of the leader board with 5 points :-(