Data & Intelligence

IBM Cognos TM1 TurboIntegrator – Comment Your Code

commentme

 

“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:

Data Intelligence - The Future of Big Data
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.

About the Author

Mr. Miller is an IBM certified and accomplished Senior Project Leader and Application/System Architect-Developer with over 30 years of extensive applications and system design and development experience. His current role is National FPM Practice Leader. His experience includes BI, Web architecture & design, systems analysis, GUI design and testing, Database modeling and systems analysis, design, and development of Client/Server, Web and Mainframe applications and systems utilizing: Applix TM1 (including TM1 rules, TI, TM1Web and Planning Manager), dynaSight - ArcPlan, ASP, DHTML, XML, IIS, MS Visual Basic and VBA, Visual Studio, PERL, Websuite, MS SQL Server, ORACLE, SYBASE SQL Server, etc. His Responsibilities have included all aspects of Windows and SQL solution development and design including: analysis; GUI (and Web site) design; data modeling; table, screen/form and script development; SQL (and remote stored procedures and triggers) development and testing; test preparation and management and training of programming staff. Other experience includes development of ETL infrastructure such as data transfer automation between mainframe (DB2, Lawson, Great Plains, etc.) systems and client/server SQL server and Web based applications and integration of enterprise applications and data sources. In addition, Mr. Miller has acted as Internet Applications Development Manager responsible for the design, development, QA and delivery of multiple Web Sites including online trading applications, warehouse process control and scheduling systems and administrative and control applications. Mr. Miller also was responsible for the design, development and administration of a Web based financial reporting system for a 450 million dollar organization, reporting directly to the CFO and his executive team. Mr. Miller has also been responsible for managing and directing multiple resources in various management roles including project and team leader, lead developer and applications development director. Specialties Include: Cognos/TM1 Design and Development, Cognos Planning, IBM SPSS and Modeler, OLAP, Visual Basic, SQL Server, Forecasting and Planning; International Application Development, Business Intelligence, Project Development. IBM Certified Developer - Cognos TM1 (perfect score 100% on exam) IBM Certified Business Analyst - Cognos TM1

More from this Author

Thoughts on “IBM Cognos TM1 TurboIntegrator – Comment Your Code”

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Subscribe to the Weekly Blog Digest:

Sign Up