Scripting and Coding As A Team Player: Documenting Your Code

When working in a team environment there's a tragic and running joke heard about documenting your code and projects in the event that you're hit by a bus. This is not a fate we wish on anyone but a morbid reminded that life can be tragic and your work is your legacy and someone will need to understand it and carry on where you left off. This is why we need to document our work, though I admit that providing clear and wonderful insight on your though processes and intentions may seems like a means by which to enhance your expend-ability. I get that. My brother-in-law never understood why we should document our work and share our knowledge as it makes devalues you to the company of they can just hire someone new and cheaper, but my contention is that if you can create solutions and document those solutions you become and maintain yourself as a value to be retained. Both arguments have validity, I choose the nobler path.

So, in Scripting, it's expected that people will look at your code. If you're on the Internet most of the content you see can be revealed by hitting F12 in your browser and entering "Developer Mode," allowing you to see what's on the page in a semi-readable format. If the site is working with sensitive information this means that the developer must make an effort to go beyond simple obfuscation and only send data to a page that the user has been granted access to, but this is on the coder to prevent access to those prying eyes.

In a team where the code you write is meant to be used and leveraged by others in your organisation there's a need to share your wealth of knowledge, even if that means that your occasional lack of brilliance is revealed in code. To make it easier to read for the team, or that bus driver that learned how to code these base-line steps will help in producing documented code, but they can also help you when you come back to a script after a break of some sort, like months of working on something else. As a coder you rarely have the luxury of building a project and walking away.

The Header:

<#
    --------------------------------------------------------------
    The HEADER - Version 1.13 - 2021-10-30 - camerons@meInc.com
   

    This is where you might describe the project, the steps and
    dependencies, the command-line options, a link to your online
    documentation, and possible what ticket/JIRA you were working
    on that this resolves. Informative and readable but brief is
    the goal.

    --------------------------------------------------------------
#>

This should be at the beginning of any script, if not from the start, then before it becomes a monster. This example, content aside, is what you might find at the top of one of my Powershell, VBScript/ASP, or PHP scripting files, though there are different commenting styles for each. In a server-side web script this would not be visible. Comments rarely are in those situations.

In HTML you can comment a page, but the entire file is generally on display and <!-- comments --> should not contain anything sensitive.

The Rest of The Story:

In the rest of your code you can use blocks like above, or notes and markers to help guide you the murky world you designed so many months in the future when you're force to tweak something. Generally this can be a tidbit like this:

 

This sort of comment is left to explain your logic, often these are present in the design-phase where you're thinking about what comes next and what needs to be done to complete the task but some of it can be left behind to help the next guy or gal trying to fix something while you're fast asleep, enjoying that you're not on-call this wekend.

 Then there's landmarks like this:

  

 This simple note placed way out to the right can help as you're scanning through lines of code, watching for landmarks so you know where you are. These can be placed at the beginning of functions or at key points to help explain the process.

Beyond:

Anything more in-depth belongs in technical documentation. While I like Confluence in my day-job, In my personal life it's Evernote, or Microsoft Word that get the nod. If you're on Linux, LibreOffice is very capable. Do not be afraid to use screenshots and be thorough in your explanations. Of course if your on GitLab or GitHub you can store your code there and use a Markdown document if you'd like. If you review my blog, this is very much how I document my work. I explain the project, requirements, process, and desired outcome as well as the caveats and hurdles where necessary. The technical documentation is at a different level than user documentation but appreciate that not everyone is as brilliant as yourself and cover things that are "just understood," to you with links and blurbs that can help someone else rank-up in their own understanding and career.