Few notes written after event 1.

As promised, today more general thoughts on scripts I've seen in both categories in the first event. I'm Polish, so I decided to blog notes both in my own language, and in English, "just in case". Also, my Polish is much better than my English (I hope!), so for people from Poland: they can read Polish version, without the pain of translating my-English to English-English. Enjoy!

English version

Polish version

One Comment

  1. Great article by Bartek, definitely click-through and read it if you're participating in scripting or scoring.

    --

    A point he raised really leaves me with an unresolved paradox, and I'm hoping someone here can give me a suggestion that resolves this.
    I care about it a bit from the perspective of "how does this affect my score?" but I think it's more important from the perspective of "what sort of example am I setting?".

    How do we balance Convention vs Accuracy in naming?

    Bartek points out that good Cmdlets are all singularly named ( get-process, get-service ).
    Which works nicely because their names accurately match what they do; interact with individual process or service objects.
    When we use these we can create a plural context for them, a set or subset of items to feed them, either with implicit or explicit Foreach logic (including wildcards which explicitly says "for each matching item")
    So even though we feed them plurals these cmd-lets work in singular context, one Process{} loop at a time, with each individual process or each individual service.

    So conventional naming (Verb-SingularNoun) represents (what I'm doing to)-(Each singular item of a potentially plural scope)

    There is a VERY small number of cmd-lets that do not address their scope-item in an individual context. Here are two examples:

    Close-AllOpenedFiles – closes ALL files opened by the ISE - according to the name of this cmdlet the scope "file" level, but more realistically the scope item is the ISE itself which has these files as it's current properties.
    Thus the only way to express what this cmdlet does is to say it "interacts with the Plurals of a Singular". There is no way to adjust the scope of the cmdlet. It will always query the Singular ISE session, and then close ALL (saved) files belonging to that session.

    Imagine if it were named Close-OpenFile. It would be inherently wrong because it misleads the user about the scope being addressed and therefore it is potentially dangerous.

    Another one is get-logproperties - this gets ALL (plural) properties of a (singular) log. It has no capability to address a single property by itself.

    Now you could argue that these cmdlets are "wrong by design" because of this limitation of having to address every sub-member of their primary target... but that's asking the wrong question.
    There are usage scenarios where this makes perfect sense. If they are wrong by design then so is the specifications given for Event #1, because we are being asked to provide a function that addresses Plural sub-items of a singular path. Like get-logProperties we are combining set identification, sub-set selection and manipulation into one unit, where strict usage would involve 3 separate steps tied via pipe or parameter. [ gci –path $dir –filter *.log | where-object {selection logic} | move-item –destination ]

    The right question to ask is: "Does their name properly reflect their capability".
    For the two items I reference they ARE named correctly because their name conveys immediately and clearly the scope within which they are working. Before a name change could happen the cmdlet should be rewritten.

    All of the singularly named cmdlets work individually with the item represented by their noun.
    But we are creating a tool that does the exact opposite, we are inputting a singular and then handling all of its child items as a group.

    The only singular in our task is the Directory, but we're explicitly not moving the source directory so we'd never call it Move-LogDirectory. The only singular we address is a directory path but no verbs appropriately express what we are doing from a directory context.

    The only noun that makes sense is File, but we do not request or expect a -file parameter... we have suddenly developed a naming paradox. It's a paradox that can only be resolved by saying "the scope of this noun is plural", but the convention we're told is "never be plural".

    The problem is that I can't find a more acceptable naming method. If a function/cmdlet is named verb-logFILE and it's ONLY input parameters DIRECTORY then this function is named WRONG. I would NEVER approve of a function name that implies individual item scope if the inputs do not permit individual scope.

    Here's an example from real life. At work I've created a script-tool that automatically resolves credential conflicts items by deleting items that match a *.Hitachi.net pattern, and then creates appropriate items with correctly formatted usernames.
    This tool is stand-alone. Like our event scope it is meant to do it's own internal selection AND manipulation as one united function.
    There is no way that any name other than reset-HitachiCreds is safe and practical to give to widespread team members. It carries it's warning in the name "this resets credentialS".

    So in all sincerity I ask:
    What is a smart way of naming a function that is intended to always work in the plural scope?

    Break readability/usability in favor of convention? move-logfile

    Break convention in favor of usability? move-logfiles

    Turn a function into a chain of piped functions? Select-archiveFile | Move-ArchiveFile

    ps.
    Not seeking to contradict anyone.
    This is Powershell ... we question what's always been and seek the better way.