Focusing on Help Driven Development

I often times write up a never ending While loop in PowerShell to run something every X minutes.  Usually, I do this if I have manually deleted a user from Azure AD and I am waiting for it to synchronize back up:

When I am done, I just [Ctrl]+[Break], or maybe I insert a condition to break once it completes.

Today, I found myself doing just this thing.  I decided, I should write that into a function so I don’t have to type it out all of the time.  I cracked open Visual Studio Code and started writing the function…

Wait, I should be using Help Driven Development!

Defining Help Driven Development

I am definitely no expert here, however, this is the gist of it: when we define a task that we need to complete, we plan on defining the problem, designing the solution, implementing the solutions, testing the solution, and throughout writing up our documentation.  What ends up happening is that we get some external forces exerted upon us and we lie to ourselves and say, “I’ll come back and write up the documentation.”  Yeah, right.

Help Driven Development takes the approach and flips it.  First, you write your help documentation.  This process also doubles as part of our design phase.  We are defining what the code should do and how it should be used.

Now, Help Driven Development is just an iteration over and above another concept called Test Driven Development that suggests… can you guess?  That we define our tests first and write out code to conform to the tests!  So, in Help Driven Development, we write the help documentation and use that to assist us in writing the tests, and then we develop the code to pass the tests.

Tools of the Trade

Everything is easier said than done, no?  Well, we have a couple of tools that help us.  First, we have Visual Studio Code.  So, open it and press [Ctrl]+[Shift]+P and get a context menu that asks to run something… I want to run Plaster, which creates from a template a framework to create a module file, the definition file, and the Pester test for it!  And then, we have Pester, which is really beyond the scope of what I am writing here, but it is the testing framework for PowerShell.

So, in the context menu, I type: Create.

It starts listing out a menu of options and I select: PowerShell: Create New Project from Plaster Template.

This launches a script in the integrated console that asks for a directory and a name.  What I get back are basically three files:

1. ModuleName.PSM1 file for the module
2. ModuleName.PSD1 file for the module definition
3. ModuleName.tests.PS1 for the Pester test

They are structured into a nice directory layout and all is well.

In the .PSM1 file, I press [Ctrl]+[Spacebar] and use my VS Code snippet for an advanced function that gives me a good starting point for the function, including help comments and advanced parameter work.  The module is available following:

https://github.com/dustindortch/xInvoke-RepeatedProcess

So, I defined some system help and created a test, then I wrote my code.  I failed a little and adjusted the help, the test, and the code.  This happened a few times then it ultimately worked out.