As a coder and avid scripter, it’s hard to not just get down to coding right away. Planning and documentation is boring. You just want to get to the fun stuff!
Although a laissez-faire attitude may work for simple scripts, you’ll soon find yourself in a world of hurt if no planning is done on larger projects. Putting together a plan, whether it be a simple back-of-the-napkin sketch or an entire project outline, is critical for ensuring success on larger projects.
If you don’t plan ahead, you’ll find yourself having to put fixes in code to cover up previous problems, introduce unnecessary performance degradation, and end up with a plate of spaghetti code. Poor planning will force you to accrue technical debt and will always result in a management nightmare.
Write Comments Before Coding
Large software projects require extensive planning before diving into code. Why shouldn’t your important PowerShell scripts get the same treatment albeit at a much smaller scale?
It may be more fun to start coding away immediately, refrain. Ask yourself what the end goal of the script is and document it with comments. Think through what the script will do before writing a single line of code. Instead, break down each task in your head and document it with simple comments in the script.
Regions are a great commenting feature to use when planning. Regions allow you to easily collapse and expand parts allowing you to pay attention to the task at hand.
Don’t worry about using a particular comment structure. Use whatever structure is most comfortable for you to guide you through the coding process when the time comes.
Tip Source: https://twitter.com/duckgoop
Further Learning
Use Your Code As a Todo List
We’ve all had those times when you’re in the middle of a script and get interrupted somehow. You may be in just the right frame of mind and on the cusp of solving a problem that’s been plaguing you for days. Or you might be building a script as fast as possible but don’t want to forget to come back to a certain area. Either way, using your code as a todo list will help.
Perhaps you know code will break under certain circumstances, see a way to improve performance or perhaps you’re working on a team and need to assign a junior developer a piece of code, try adding ## TODO to the code at that particular line.
The comment doesn’t have to specifically be ## TODO. The point here is to create a “comment flag” that points to areas that need to be addressed at some point. At some point in the future, you can then perform a search on the codebase for that flag and find all of the instances to address.
Tip Source: https://twitter.com/guyrleech