When I mention to people my programming languages of choice are Ruby and PowerShell, I get some funny looks and many times some very confused looks.  Early in my career I was a very big Microsoft fan-boy but over time, I learned that “every tool has its job and not everything is a nail.”  This lesson took me into many programming languages and opened my eyes to opportunities that I otherwise would not have learned.  The point is that each of those languages whether it be PoSH, Ruby, NodeJS, or even PHP, for goodness sake, have special requirements and capabilities that makes them powerful in their own way.  The important fact that I have learned is that no matter what language, it pays to structure your project in a clearly defined way and documentation is king.

Who doesn’t like playing ‘Where is Waldo’ with someone else’s code?

A few days ago, I was chatting with a fellow PoSH junky and we were reminiscing about reviewing our old code.  You know the code that I am talking about.  The script that makes a Unicorn carrying pots of gold magically appear while whistling Dixie.  Yes, that code.  When you go back and look at this masterpiece months later because you just need that one part and you have no idea at what in the world is starting back at you.  So you spend hours reverse-engineering your functions and variables to decide what is happening and what you need to extract.  When I was a young developer, I would just skip the comments.  I mean I have an exceptional memory so why even waste my cycles on comments?  As I have matured in my role, I realized that it isn’t a matter of how much I can remember but is it really worth it?

There is another important point to taking the time to document early and even for a simple 10 line script – delegation.  At some point in your career, you will likely turn that script over to another developer.  You might get a promotion or win the lottery or simply need to debug/reuse your code one day.

There is another good reason to document your notes.  Often times, I need to decide that is more of a compromise than I would like.  In this case, it is very helpful for me to have a block-note that covers the logic and reasoning.  It also serves as a flag later when I may want to refactor or update my code.  In other programming languages we would typically leverage a comment block with a TODO: flag and then detail what we should revisit later.  This visual cue is invaluable when the moment comes and you need to share your script with a colleague or even start a joint collaboration. This is a very important habit to begin and it starts by following a few simple tricks the moment that you open your IDE and your first file.

• Add notes to the page for the sections that you expect to create:  This will force you to start thinking about the structure of your script and what you want to see happen.  Often, I don’t know exactly how I will write the code, but I do know what I want the code to do.  These notes help guide your code and ultimately your tests.
• Create a TODO list and keep your hair: As much as I would like, I never can complete my scripts in a single sitting but I am constantly coming up with ideas.  The best place to put this is not that old, ratty notebook on your desk but right there in your code.  Notebooks come and go… but diamonds… err I mean your code is forever.
• Inline comments are great ways to point out important variable declarations or checks: This is something that I have just started doing and it is fairly common in Ruby and NodeJS, but not so much in PoSH code.  I find this very beneficial when I am looking at a script with 1000+ lines of code (not my biggest but we will talk about code structure later).  I can remember what updated that variable value and why it is important or why we need to re-validate the parameter so far down the code line.
• Perfect comments are not required until you commit your code: This means that it doesn’t matter what you put in there just make the comments helpful and worry about polishing them later.  This another area that has taken me some time to realize.  I am an extremely pedantic person and I want to make my comments the same.  On the other hand, I can’t always be as clear as I want in the amount of time that I have.  I have to remember every day to do this.
• Section BEGIN and END comments are always a plus: Add the head comment and an end comment so that it is easier to check large code bases.  Start the habit even on your small projects and it will make your life easier.

I hope that these suggestions help as you start your next project or as you work on your code today. Remember,refine these skills daily and it is not something that just happens. Come back tomorrow for another session of Building a Solid Foundation where we will tackle the challenges of how Modular is too Modular for your code.