Documenting scripts and source code

When writing applications, it is vital to be able to look back at your code and understand exactly what each line of code does as quickly as possible. Retrospectively Documenting scripts and source code is time consuming and prone to error, so its best to write the comments either as you are writing the code, or as soon as a particular block of code is complete. Here’s how to do it…

When writing applications or scripting useful functions, it is always helpful to document the code as you go along so that, should you ever need to tweak the code, you’ll know exactly what each line of code does at a glance.  The keyword or character that you use to mark the line as a special comment line will vary depending on the language that you are using.

Fortunately Microsoft have very kindly standardised on the line starting with REM for Visual Basic which then renders everything after that keyword as a comment for instance:

REM This loop acts a counter
REM set the initial count value to 0
i=0

REM set up a loop that executes until the counter value reaches 10
do while i <= 10

REM write to screen the current value of the counter
Response.Write "i currently equals: " & i & "<br>"

REM add one to the value of the counter
i = i + 1

REM Restart the loop until the counter is equal to 10
loop
REM End the loop

As you can see, by using REM I can tell myself or another technician modifying this script exactly what each line of code does and why. Useful! I document the whole of my Cisco network in this way!

Other languages