Teach Splating or Die!

Intro

This post is directed at mentors, trainers, documentation authors, and forum/chat helpers in the PowerShell community. This post is not a tutorial on splatting. I think the topic of splatting has been covered very well by many others.

I am imploring those of you in the PowerShell community to teach splatting early and often. By early, I mean it should be covered in the first few lessons of any 101 materials. By often, I mean that you should stop using backticks and consider using splats for any thing that uses 3 or more parameters.

I have had many discussions with many community leaders over the years and I'm a bit disappointed in the general aversion to teaching splatting as a part of introductory PowerShell. I have heard endless excuses that all sound like "my students are stupid" in my head. I'm sure many of you are making such arguments with the kindest of intentions, but I can't help but think you are insulting PowerShell novices.

I hope this blog post can assist in changing your mind and provide some guidance on how to approach teaching the subject early and often.

When Should I Teach Splatting?

I truly believe that we should be teaching splatting at the very beginning of a novice's PowerShell Journey. This will enable students to avoid common pitfalls that lead to unreadable, unclean, and unmaintainable code. It will shield them from learning about the perilous backtick and hopefully steer them from ever using them.

I have taught this to dozens of people new to PowerShell and even new to command lines and programming. I do so by teaching about them right as I'm teaching about commands. My general flow is:

1. This is a command.
2. This is a command with parameters.
3. This is splatting.

I don't even call it a Hash Table unless we have covered data types. I often only cover data types when someone will be programming in PowerShell and not console users. If I am teaching data types, I teach them before commands. If the student is familiar with Data Types in other languages, I provide a cliff notes on the PowerShell and .NET nuances.The result is that if the student already knows data types I can call it a hash table. If not, this is just splatting and I can connect the dots with hash tables later.

I also teach that anything over 3 parameters in a script must use a splat. This gets the student using them often from the very beginning and reinforces their new found skill. So many commands need 3 or more parameters.

I've had great success with this. I might get some questions about the at symbol and squiggles. But for the most part I can hand-wave it as not being entirely important right now what exactly they mean and that the general structure is more important. But I usually have my students using splats judiciously in very early stages.

The trick is, students don't NEED to understand the in-depth explanation of what is going on unless you are approaching PowerShell from an inside-out approach. If you are using an inside-out approach you are likely targeting a highly experience or technical audience anyway (I would recommend against this approach for those new to coding). The student just needs to know that for any command with 3 or more parameters, use this pattern. You can explain how it makes code cleaner, maintainable, and flexible and not focus on the underlying data type or what the at and squiggles mean.

My Students Struggle with Splatting Early. I Teach it as an Advanced Topic.

Teaching is hard. We have to explain complex subjects in simple ways to students with little context. I think understanding that is a huge key to success in teaching splatting early. I have observed how many others teach splatting and I believe the problem is not with the students, but with the delivery.

Some phrasing to avoid:

1. This is a hash table, we'll cover these later.
2. This is an advanced method, we'll cover it in depth later.
3. This is only useful for long commands.
4. The at-symbol token is .
5. Ok, let's cover what Hash Tables are before moving on.
6. Splatting is only used for when you want to extend parameters.

 I have seen these phrases pop up and the students become instantly distracted and confused. With number 1, you are introducing a new concept in the middle of introducing a new concept then short-circuiting the new-new concept and returning to the new concept. This leaves the student stuck on what a hash table is and unable to refocus on splatting.

With number 2, you are calling it an advanced concept in material that is likely aimed at the novice. That makes it easy for the student to write off as something they do not need to pay attention to for now. Maybe they drop off after they get the very basics out of the way and never venture into your 202 materials. This leaves a gap in their understanding of splatting.

With number 3, you are just wrong, IMO. Splatting is good practice even for single parameter commands. This is especially true when you format splat hash tables to have one parameter per line. When scripts start making their way to source control, changes to simple lines like that are way easier to review. It will really improve maintainability of code. Teaching students it is only useful for long commands will discourage them from this good practice.

With number 4, unless you are teaching a course on PowerShell internals, do. not. mention. parsing. in. 101. materials. Plenty of PowerShell "heavy hitters" are completely oblivious to PowerShell internals. There's nothing wrong with that. That's the entire point of an interpreted language. Covering this in 101 material is going to confuse your students who are new to coding unless you do a damn good job at an inside-out approach. In which case, commands and data types will probably come late in your materials anyway.

With number 5 you are doing the same as number 1, but instead of short-circuiting, you are side tracking. You introduce splatting, introduce hash tables, teach hash tables, return to splatting, teach splatting. That's a jarring experience for a learner. It is better, IMO, to teach one thing at a time and move on. Introduce dependencies before they are required or skip them altogether, and say, "this is splatting, this is the form, and that's all you need to know for now."

Number 6 is similar to number 3. It's only one reason of many to splat. In my experience, it works best to cover advanced splatting topics later. At the beginning, you only need to introduce splatting and get the student using it. You can gradually introduce extending splats as you delve into conditionals and input handling.

But All My Documentation Has Backticks!

That sucks. You are probably the victim of "those who came before." The truth is, those who were teaching/documenting PowerShell before didn't have the benefit of a decade's worth of learning. So many documents, videos, slide decks, presentations, and books have backticks in them. The reality is that backticks absolutely suck in documentation. They often seem like mistakes on the page or misguide readers/viewers into thinking white space after the backtick is ok.

We, as the newer "generations" of PowerShell authors, have an opportunity to change course. I'm not suggesting you go back and edit all of your documentation. But, you should go back and edit your most impactful documents if you can.

There is some concern that those new to the language may not comprehend the documentation if it has splatting. I can agree with this a bit, but that's why we need to bot update/change our documentation and update/change our training. Though, I have one mentee who is new to coding and PowerShell who was able to intuit splatting form examples and documentation. They didn't quite bridge the gap to writing splats, but they could understand the documentation without formal splat training. It also opened the conversation about splatting and presented a learning opportunity.

Mark, Why Do You Care so Much about This?

My "Bye Bye Backtick: Natural Line Continuations in PowerShell" post is my most viewed post of all time. I see it mentioned everywhere. Why is it so popular? Because backticks suck and people want to split commands across multiple lines. It also grinds my gears that splatting is taught as an advanced topic when it is so flipping easy to do.

We have interviewed 100's of PowerShell coders for positions at work. Most cannot splat or have never heard of it. Splatting is a necessity in any shop with large PowerShell codebases. It's an essential skill the moment you start having more than one person working on your PowerShell code, closed-sourced or open-sourced.

Splatting is so simple, I have been able to teach people splatting in only 5 minutes during the interview process. That indicates to me that there is simply no excuse to not teach it in 101 content. I think it is an extremely valuable tool to have in the tool box and is easy enough to learn early.

I also have a vested interest in breaking the habits in PowerShell training that are producing PowerShell users who never advance beyond 202 content. If PowerShell as a language is to survive outside the Windows/Microsoft ecosystem, it is going to require more 303 and 404 level training and coders. Otherwise, employers will just hire Python coders who get formal Computer Science degrees in Python.

To me, teaching splatting (and proposed and implemented alternatives other than backticks) is a matter of PowerShell's longevity as a language. As it stands now, the ways we train PowerShell users will not sustain that longevity as market forces will drive them to Go or Python to seek career advancement and better pay.