Some Comments about Commenting

 Developing TurboIntegrator solutions can be both challenging and fulfilling but having to “revisit” code after time has passed – either to modify or debug it – typically is not a fun task, since its objective or what the original developer was thinking while writing it (even if it was you) may have been lost to time.

A TurboIntegrator or “TI” script consisting of lines and lines of unstructured and uncommented code not only is difficult to read and understand, but also effects the sustainability of the overall solution it is a member of.

As a developer you may have a “personal style” when it comes to developing these scripts and that’s fine, however, as a professional you need to adhere to some basic standards and best practices to produce more maintainable applications.

I’ve found the following are some “commonsense” guidelines to follow when writing TI scripts:

  • Use whitespace (spaces, tabs or line breaks) to separate logical sections of code
  • Follow a consistent indenting style – indents should reveal the underlying logic and program flow. I find that 9 spaces from the left of each indent presents well.
  • Use a standard “header block” to identify what is in the script, who wrote it, the date it was written, and an explanation of what is being solved by the script.
  • Data items whose values cannot change during the script’s execution should be defined using “user friendly” constants for readability.
  • Pick a naming convention and name script variables consistently. When possible, consider developing a kind of “data dictionary” allowing data to be referred to with the same name throughout the application.
  • Make documentation portable – consider using cubes to hold common information that the scripts will use rather than recording logic in multiple scripts (this can constant or calculated values).
  • Modularize your code! Separate script functions into independent pieces or building blocks, each containing all the “parts” needed to execute a single aspect or functional piece of an overall objective. This will reduce the size of your scripts and ease debugging and validation.
  • At minimum, partition the scripts metadata and data tab operations. You may even consider separating what’s happening in each of these tabs into different scripts.
  • Make use of the “ExecuteProcess” command. Perhaps use a “master” process to determine which “logical path” to proceed with then use the ExecuteProcess function to run a different TI script for each.
  • Use comments liberally! Adding comments to your TurboIntegrator scripts is one of the simplest “best practices” you can implement!

Comment Categories

The following describes the basic categories of comments and recommendations for use of each:

Explaining – This type of comment can be used to clarify tricky or very complicated code logic. These are a must, but remember – aim to “simplify”, not “explain” the logic.

Marking – Marking comments are used around “stubbed-out” or “logical sections” of script. The “rule of thumb” here is to use a identical marker (for example:  #****** TO DO *********). Being consistent with your marker comments also allows automation later with utilities.

Summarizing – These comments summarize the code operations (try for 1-2 sentences). These should be used abundantly – especially in multi-developer environments.

Describing – “Describing comments” explains the purpose of a particular block of code – you should try to use approximately one description comment statement in roughly every 10 lines of script code.

Non-Functional – Non-functional comments should contain information such as author, version, original date, revised date, etc. These comments are best implemented in a standardized “comment block” – located in the prolog of every TurboIntegrator script.

Repeating – Repeating comments are used to restate the program script in words (rather than asking the reader to translate or understand the scripting syntax). Use this type of comment carefully (typically found more in the scripts header block) since adding a “narrative” throughout the script tends to just obscure the real code.

Conclusion

The earlier the adoption of a commenting standard or style, the sooner it will become a natural habit which will, inevitably, result in “professional looking” and easier to understand and maintain code.