Challenge

Create in-line documentation in scripts and functions that:

• enables using the script again after weeks or months of disuse.
• makes using the script possible without having to review the source code
• reduces the learning curve to put a script or function to work
• provides a basis for understanding what to add to create a more robust version

Benefits

• Realize the greater productivity benefits from investments in creating a script through more use with less restart time
• Reduce re-invention of solutions to already solved problems

Assumptions

• The function will probably be used again
• The development time will take at least two hours
• You already know about the elements of the in-line documentation block used in PowerShell Advanced Functions.

Solution

A simple change in development process for a script or function can dramatically improve the final code quality.  The solution is putting in-line documentation to work in developing the solution.  A change in the testing process can result in in-line examples that shorten the subsequent time to re-use.
This is is a process change and NOT a coding trick, although a change in how you code to develop and test the function will help. The first two steps focus on getting clear on what you’re doing.  The remaining steps are changes in coding practice.

The steps are:

1. Create a blog post or process ‘readme’ description to define what the function will do. Estimated time:  30-45 minutes
   This can be a general post not unlike this one.  It tells in general terms what the challenge is, what the expected benefits are, and how you plan to meet the challenge.  How you expect to solve the challenge can be high level.  You should include any links to related sites that you considered in preparing for the solution.  Why you do this is to get clear about what you plan to accomplish. 
   If you do not have a blog, you can create a ‘readme’ document that may later be uploaded to a repository or saved in the same folder with the source for the function.  I would recommend using MarkDown for composition and keeping the file as a text file.  Do not use word processor files.
   Whether you do this depends on the complexity of the problem to solve.  If it will require more than two hours to develop, consider doing this step.
2. Create a statement of what you will do as your next step. Estimated time:  10 minutes
   This will be what you expect to accomplish in the two hour development block of time.  Handwrite (yes, do this by hand) the date of when you will do it, what goal is supported by what you’re doing, and what you will be doing.  Be general about the goal.  it should be one sentence.  Be specific about what you will be doing, even if you don’t know how you’ll accomplish it.  Make sure this is something you believe you can complete in the two hour block. 
   I use steno pads for this task.  The write-up is at most both sides of the page.  It takes less than ten minutes to create.
   Oh – writing this by hand – preparing the ‘next step’ statement this way takes advantage of brain chemistry stimulated by writing by hand.  The same electrochemical reaction does NOT occur when typing.
3. Begin writing the script or function, focusing on in-line documentation and the parameters needed.  Estimated time:  2 hours+
   The assumption is the script or function will be an Advanced Function, which uses parameters.  The intent of the first session is to frame the function.  This is the time to begin the in-line documentation.  If you’ve written the blog entry, the summary and process description should be mostly a cut-and-paste.  If some time has passed since writing the blog entry (be it several hours or, best of all, overnight), you may surprise yourself with how easily you can write these sections.  You may find yourself altering the initial blog post or ‘readme’.
4. Within the script, create the function and follow it with the functions calls and parameters.  Estimated time:  included in development time
   This is where the magic happens.  Define values for all the parameters for the test case.  Set up any piping or use of other functions.  Populate variables with the same names as the parameters.  Use splatting to submit all the test values to the new function.
   The first goal is to be able to invoke the script and have the function run successfully.  Anyone running the script would have the function run properly, at least for the defined values.
   The second goal is being able to repeat the successful use at some future date.  For that, the in-line documentation must have all the values you used, or be able to recreate them.  If you import a CSV, you may want to included as block comments in this section at least a few objects from the CSV.  This would enable re-created the CSV file to re-create the run.
5. When the function is running successfully, move the function call and parameter values to the in-line documentation as an example.  Estimated time:  5 minutes
   Move the section that follows the function into the in-line example of the function.  It will go into the documentation block.  
6. Copy the function call and parameter section back to the blog post or ‘readme’ documentation.  Estimated time:  5 minutes
   In addition to the in-line documentation, this provides a way for future users (including yourself) to replicate the run and more quickly understand how the function works.

The pay-offs are:

• with a description of what is being done on the front-end, you will write a better function (in addition to creating better documentation for it).
• with a precise and easily replicable set of run instructions, understanding and putting the function to work is much faster.