{"id":3934,"date":"2023-05-22T14:56:16","date_gmt":"2023-05-22T14:56:16","guid":{"rendered":"https:\/\/quebit.com\/askquebit\/?p=3934"},"modified":"2023-06-08T15:50:35","modified_gmt":"2023-06-08T15:50:35","slug":"some-comments-about-commenting","status":"publish","type":"post","link":"https:\/\/quebit.com\/askquebit\/some-comments-about-commenting\/","title":{"rendered":"Some Comments about Commenting"},"content":{"rendered":"<p><strong>Some Comments about Commenting<\/strong><\/p>\n<p><strong>\u00a0<\/strong>Developing <a href=\"https:\/\/www.ibm.com\/docs\/en\/planning-analytics\/2.0.0?topic=turbointegrator-basics\">TurboIntegrator<\/a> solutions can be both challenging and fulfilling but having to \u201crevisit\u201d code after time has passed \u2013 either to modify or debug it \u2013 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.<\/p>\n<p>A TurboIntegrator or \u201cTI\u201d 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.<\/p>\n<p>As a developer you may have a \u201cpersonal style\u201d when it comes to developing these scripts and that\u2019s fine, however, as a professional you need to adhere to some basic standards and best practices to produce more maintainable applications.<\/p>\n<p>I\u2019ve found the following are some \u201ccommonsense\u201d guidelines to follow when writing TI scripts:<\/p>\n<ul>\n<li>Use whitespace (spaces, tabs or line breaks) to separate logical sections of code<\/li>\n<li>Follow a consistent indenting style \u2013 indents should reveal the underlying logic and program flow. I find that 9 spaces from the left of each indent presents well.<\/li>\n<li>Use a standard \u201cheader block\u201d 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.<\/li>\n<li>Data items whose values cannot change during the script\u2019s execution should be defined using \u201cuser friendly\u201d constants for readability.<\/li>\n<li>Pick a naming convention and name script variables consistently. When possible, consider developing a kind of \u201cdata dictionary\u201d allowing data to be referred to with the same name throughout the application.<\/li>\n<li>Make documentation portable \u2013 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).<\/li>\n<li>Modularize your code! Separate script functions into independent pieces or building blocks, each containing all the \u201cparts\u201d 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.<\/li>\n<li>At minimum, partition the scripts metadata and data tab operations. You may even consider separating what\u2019s happening in each of these tabs into different scripts.<\/li>\n<li>Make use of the \u201cExecuteProcess\u201d command. Perhaps use a \u201cmaster\u201d process to determine which \u201clogical path\u201d to proceed with then use the <a href=\"https:\/\/www.ibm.com\/docs\/en\/planning-analytics\/2.0.0?topic=pctf-executeprocess\">ExecuteProcess<\/a> function to run a different TI script for each.<\/li>\n<li>Use comments liberally! Adding comments to your TurboIntegrator scripts is one of the simplest \u201cbest practices\u201d you can implement!<\/li>\n<\/ul>\n<p><strong>Comment Categories<\/strong><\/p>\n<p>The following describes the basic categories of comments and recommendations for use of each:<\/p>\n<p><strong>Explaining &#8211; <\/strong>This type of comment can be used to clarify tricky or very complicated code logic. These are a must, but remember \u2013 aim to \u201csimplify\u201d, not \u201cexplain\u201d the logic.<\/p>\n<p><strong>Marking &#8211; <\/strong>Marking comments are used around \u201cstubbed-out\u201d or \u201clogical sections\u201d of script. The \u201crule of thumb\u201d here is to use a identical marker (for example: \u00a0#****** TO DO *********). Being consistent with your marker comments also allows automation later with utilities.<\/p>\n<p><strong>Summarizing &#8211; <\/strong>These comments summarize the code operations (try for 1-2 sentences). These should be used abundantly \u2013 especially in multi-developer environments.<\/p>\n<p><strong>Describing &#8211; <\/strong>\u201cDescribing comments\u201d explains the purpose of a particular block of code \u2013 you should try to use approximately one description comment statement in roughly every 10 lines of script code.<\/p>\n<p><strong>Non-Functional &#8211; <\/strong>Non-functional comments should contain information such as author, version, original date, revised date, etc. These comments are best implemented in a standardized \u201ccomment block\u201d \u2013 located in the prolog of every TurboIntegrator script.<\/p>\n<p><strong>Repeating &#8211; <\/strong>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 \u201cnarrative\u201d throughout the script tends to just obscure the real code.<\/p>\n<p><strong>Conclusion<\/strong><\/p>\n<p>The earlier the adoption of a commenting standard or style, the sooner it will become a natural habit which will, inevitably, result in \u201cprofessional looking\u201d and easier to understand and maintain code.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Some Comments about Commenting \u00a0Developing TurboIntegrator solutions can be both challenging and fulfilling but having to \u201crevisit\u201d code after time has passed \u2013 either to modify or debug it \u2013 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&hellip;<\/p>\n","protected":false},"author":6,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[24],"tags":[85,77,36,40,82,83,80,81],"class_list":["post-3934","post","type-post","status-publish","format-standard","hentry","category-ibm","tag-cognos-tm1","tag-ibm","tag-planning-analytics","tag-tech-tips","tag-ti","tag-tm1","tag-turbo-integrator","tag-turbointegrator"],"acf":[],"yoast_head":"<!-- This site is optimized with the Yoast SEO plugin v27.3 - https:\/\/yoast.com\/product\/yoast-seo-wordpress\/ -->\n<title>Some Comments about Commenting - QueBIT<\/title>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/quebit.com\/askquebit\/some-comments-about-commenting\/\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Some Comments about Commenting - QueBIT\" \/>\n<meta property=\"og:description\" content=\"Some Comments about Commenting \u00a0Developing TurboIntegrator solutions can be both challenging and fulfilling but having to \u201crevisit\u201d code after time has passed \u2013 either to modify or debug it \u2013 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&hellip;\" \/>\n<meta property=\"og:url\" content=\"https:\/\/quebit.com\/askquebit\/some-comments-about-commenting\/\" \/>\n<meta property=\"og:site_name\" content=\"QueBIT\" \/>\n<meta property=\"article:published_time\" content=\"2023-05-22T14:56:16+00:00\" \/>\n<meta property=\"article:modified_time\" content=\"2023-06-08T15:50:35+00:00\" \/>\n<meta name=\"author\" content=\"Patrick Quirke\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"Written by\" \/>\n\t<meta name=\"twitter:data1\" content=\"Patrick Quirke\" \/>\n\t<meta name=\"twitter:label2\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data2\" content=\"3 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\\\/\\\/schema.org\",\"@graph\":[{\"@type\":\"Article\",\"@id\":\"https:\\\/\\\/quebit.com\\\/askquebit\\\/some-comments-about-commenting\\\/#article\",\"isPartOf\":{\"@id\":\"https:\\\/\\\/quebit.com\\\/askquebit\\\/some-comments-about-commenting\\\/\"},\"author\":{\"name\":\"Patrick Quirke\",\"@id\":\"https:\\\/\\\/quebit.com\\\/askquebit\\\/#\\\/schema\\\/person\\\/51bf83d531948247370683787d0f46ff\"},\"headline\":\"Some Comments about Commenting\",\"datePublished\":\"2023-05-22T14:56:16+00:00\",\"dateModified\":\"2023-06-08T15:50:35+00:00\",\"mainEntityOfPage\":{\"@id\":\"https:\\\/\\\/quebit.com\\\/askquebit\\\/some-comments-about-commenting\\\/\"},\"wordCount\":680,\"commentCount\":0,\"keywords\":[\"Cognos TM1\",\"IBM\",\"Planning Analytics\",\"Tech Tips\",\"TI\",\"TM1\",\"Turbo Integrator\",\"TurboIntegrator\"],\"articleSection\":[\"IBM\"],\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"CommentAction\",\"name\":\"Comment\",\"target\":[\"https:\\\/\\\/quebit.com\\\/askquebit\\\/some-comments-about-commenting\\\/#respond\"]}]},{\"@type\":\"WebPage\",\"@id\":\"https:\\\/\\\/quebit.com\\\/askquebit\\\/some-comments-about-commenting\\\/\",\"url\":\"https:\\\/\\\/quebit.com\\\/askquebit\\\/some-comments-about-commenting\\\/\",\"name\":\"Some Comments about Commenting - QueBIT\",\"isPartOf\":{\"@id\":\"https:\\\/\\\/quebit.com\\\/askquebit\\\/#website\"},\"datePublished\":\"2023-05-22T14:56:16+00:00\",\"dateModified\":\"2023-06-08T15:50:35+00:00\",\"author\":{\"@id\":\"https:\\\/\\\/quebit.com\\\/askquebit\\\/#\\\/schema\\\/person\\\/51bf83d531948247370683787d0f46ff\"},\"breadcrumb\":{\"@id\":\"https:\\\/\\\/quebit.com\\\/askquebit\\\/some-comments-about-commenting\\\/#breadcrumb\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\\\/\\\/quebit.com\\\/askquebit\\\/some-comments-about-commenting\\\/\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\\\/\\\/quebit.com\\\/askquebit\\\/some-comments-about-commenting\\\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\\\/\\\/quebit.com\\\/askquebit\\\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Some Comments about Commenting\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\\\/\\\/quebit.com\\\/askquebit\\\/#website\",\"url\":\"https:\\\/\\\/quebit.com\\\/askquebit\\\/\",\"name\":\"QueBIT\",\"description\":\"QueBIT\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\\\/\\\/quebit.com\\\/askquebit\\\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"en-US\"},{\"@type\":\"Person\",\"@id\":\"https:\\\/\\\/quebit.com\\\/askquebit\\\/#\\\/schema\\\/person\\\/51bf83d531948247370683787d0f46ff\",\"name\":\"Patrick Quirke\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\\\/\\\/secure.gravatar.com\\\/avatar\\\/c2c5ed78cce873ccf3eb420007d81d4fcdacb9bf4936d8b0b463390b69fd05ff?s=96&d=mm&r=g\",\"url\":\"https:\\\/\\\/secure.gravatar.com\\\/avatar\\\/c2c5ed78cce873ccf3eb420007d81d4fcdacb9bf4936d8b0b463390b69fd05ff?s=96&d=mm&r=g\",\"contentUrl\":\"https:\\\/\\\/secure.gravatar.com\\\/avatar\\\/c2c5ed78cce873ccf3eb420007d81d4fcdacb9bf4936d8b0b463390b69fd05ff?s=96&d=mm&r=g\",\"caption\":\"Patrick Quirke\"},\"sameAs\":[\"https:\\\/\\\/quebit.com\\\/askquebit\\\/\"],\"url\":\"https:\\\/\\\/quebit.com\\\/askquebit\\\/author\\\/pquirke\\\/\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"Some Comments about Commenting - QueBIT","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/quebit.com\/askquebit\/some-comments-about-commenting\/","og_locale":"en_US","og_type":"article","og_title":"Some Comments about Commenting - QueBIT","og_description":"Some Comments about Commenting \u00a0Developing TurboIntegrator solutions can be both challenging and fulfilling but having to \u201crevisit\u201d code after time has passed \u2013 either to modify or debug it \u2013 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&hellip;","og_url":"https:\/\/quebit.com\/askquebit\/some-comments-about-commenting\/","og_site_name":"QueBIT","article_published_time":"2023-05-22T14:56:16+00:00","article_modified_time":"2023-06-08T15:50:35+00:00","author":"Patrick Quirke","twitter_card":"summary_large_image","twitter_misc":{"Written by":"Patrick Quirke","Est. reading time":"3 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"Article","@id":"https:\/\/quebit.com\/askquebit\/some-comments-about-commenting\/#article","isPartOf":{"@id":"https:\/\/quebit.com\/askquebit\/some-comments-about-commenting\/"},"author":{"name":"Patrick Quirke","@id":"https:\/\/quebit.com\/askquebit\/#\/schema\/person\/51bf83d531948247370683787d0f46ff"},"headline":"Some Comments about Commenting","datePublished":"2023-05-22T14:56:16+00:00","dateModified":"2023-06-08T15:50:35+00:00","mainEntityOfPage":{"@id":"https:\/\/quebit.com\/askquebit\/some-comments-about-commenting\/"},"wordCount":680,"commentCount":0,"keywords":["Cognos TM1","IBM","Planning Analytics","Tech Tips","TI","TM1","Turbo Integrator","TurboIntegrator"],"articleSection":["IBM"],"inLanguage":"en-US","potentialAction":[{"@type":"CommentAction","name":"Comment","target":["https:\/\/quebit.com\/askquebit\/some-comments-about-commenting\/#respond"]}]},{"@type":"WebPage","@id":"https:\/\/quebit.com\/askquebit\/some-comments-about-commenting\/","url":"https:\/\/quebit.com\/askquebit\/some-comments-about-commenting\/","name":"Some Comments about Commenting - QueBIT","isPartOf":{"@id":"https:\/\/quebit.com\/askquebit\/#website"},"datePublished":"2023-05-22T14:56:16+00:00","dateModified":"2023-06-08T15:50:35+00:00","author":{"@id":"https:\/\/quebit.com\/askquebit\/#\/schema\/person\/51bf83d531948247370683787d0f46ff"},"breadcrumb":{"@id":"https:\/\/quebit.com\/askquebit\/some-comments-about-commenting\/#breadcrumb"},"inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["https:\/\/quebit.com\/askquebit\/some-comments-about-commenting\/"]}]},{"@type":"BreadcrumbList","@id":"https:\/\/quebit.com\/askquebit\/some-comments-about-commenting\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/quebit.com\/askquebit\/"},{"@type":"ListItem","position":2,"name":"Some Comments about Commenting"}]},{"@type":"WebSite","@id":"https:\/\/quebit.com\/askquebit\/#website","url":"https:\/\/quebit.com\/askquebit\/","name":"QueBIT","description":"QueBIT","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/quebit.com\/askquebit\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"en-US"},{"@type":"Person","@id":"https:\/\/quebit.com\/askquebit\/#\/schema\/person\/51bf83d531948247370683787d0f46ff","name":"Patrick Quirke","image":{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/secure.gravatar.com\/avatar\/c2c5ed78cce873ccf3eb420007d81d4fcdacb9bf4936d8b0b463390b69fd05ff?s=96&d=mm&r=g","url":"https:\/\/secure.gravatar.com\/avatar\/c2c5ed78cce873ccf3eb420007d81d4fcdacb9bf4936d8b0b463390b69fd05ff?s=96&d=mm&r=g","contentUrl":"https:\/\/secure.gravatar.com\/avatar\/c2c5ed78cce873ccf3eb420007d81d4fcdacb9bf4936d8b0b463390b69fd05ff?s=96&d=mm&r=g","caption":"Patrick Quirke"},"sameAs":["https:\/\/quebit.com\/askquebit\/"],"url":"https:\/\/quebit.com\/askquebit\/author\/pquirke\/"}]}},"_links":{"self":[{"href":"https:\/\/quebit.com\/askquebit\/wp-json\/wp\/v2\/posts\/3934","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/quebit.com\/askquebit\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/quebit.com\/askquebit\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/quebit.com\/askquebit\/wp-json\/wp\/v2\/users\/6"}],"replies":[{"embeddable":true,"href":"https:\/\/quebit.com\/askquebit\/wp-json\/wp\/v2\/comments?post=3934"}],"version-history":[{"count":3,"href":"https:\/\/quebit.com\/askquebit\/wp-json\/wp\/v2\/posts\/3934\/revisions"}],"predecessor-version":[{"id":3937,"href":"https:\/\/quebit.com\/askquebit\/wp-json\/wp\/v2\/posts\/3934\/revisions\/3937"}],"wp:attachment":[{"href":"https:\/\/quebit.com\/askquebit\/wp-json\/wp\/v2\/media?parent=3934"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/quebit.com\/askquebit\/wp-json\/wp\/v2\/categories?post=3934"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/quebit.com\/askquebit\/wp-json\/wp\/v2\/tags?post=3934"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}