IBM Cognos TM1 TurboIntegrator – Comment Your Code

“Either positive or negative comments are good because it shows I am still relevant” – Justin Guarini

In all of my years of coding and testing TurboIntegrator scripts, my biggest pet peeve has to be opening a TI script and seeing lines and lines of unstructured, un-commented code.

I’ve heard all the excuses: “self-documenting”, “didn’t have time”, “so many developers, and so many personal styles”, etc.

I don’t except any of this and you shouldn’t either. Professionals adhere to basic standards and best practices and in doing so produce more maintainable applications.

The following are some common sense guidelines to follow when writing TI:

• Use whitespace and comments –liberally!
• Follow a consistent indenting style – indents should reveal the underlying logic and program flow
• Make documentation portable – consider using cubes to hold common information that the scripts will use rather than recoding logic in multiple scripts
• Modularize your code!
• At minimum, partition metadata and data operations
• Make use of the “ExecuteProcess” command
• Use “user friendly” constants for readability
• Use a standard “header block”

Categories of Comments

Commenting is one of the easiest “best practices” you can adopt! The following explains the basic categories of comments and recommendations for use of each:

The Future of Big Data

With some guidance, you can craft a data platform that is right for your organization’s needs and gets the most return from your data capital.

Get the Guide

Repeating

Repeating comments are used to restate the program script in words (rather than asking the reader to translate or understand the scripting syntax). Its best to avoid these types of comments as it tends to just obscure the real code.

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 always use a standardized marker (e.g. #****** TO DO *********).

Summarizing

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

Describing

“Describing comments” explain the purpose of a particular block of code – you should try to use approximately one description comment statement per 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.

Conclusion

Adopting a “comment standard” for all TurboIntegrator scripts will result in a “professional looking” and easier to understand and maintain application. The earlier you start commenting, the sooner it will become a natural habit.