AF Analytics - Commenting your work

Blog Post created by asoudek on Aug 31, 2016

Insert comments into your Variables so you and others can understand what you did later

Have you ever written an equation or a piece of code that made sense to you at the time only to come back a few weeks later (or in my case the next day) and wonder what you were thinking?  Worse yet, looking over somebody else’s effort and trying to decipher it?  Then you might find this section valuable to you.  A good practice is to always document and/or reference your calculations.  You may not know, but you can add comments to the equations you write, and stop having to spend time reinterpreting the calculations you or someone else wrote some time ago.  The sections below show you how to create single and multiple line comments, and how to make your equations more readable.


Single Line Comments

To add a comment to the expression in a Variable you need two things: first, you use // to preface the comment and then at the end of the comment press the Shift-Enter key combination.  You can add the comment at the beginning or at the end of the equation, but personally, it makes more sense to me at the beginning.  You can also add comments to the end of a line in the expression.


The set of equations in the Figure below are calculating the percent grade change during casting of steel I-beams.  As you can see without comments it is not easy to understand the calculation.



Adding comments makes the code more understandable, see Figure below.  Note that some comments are interspersed in the expression, like the Pct Variable in the Figure below.


Multiple Line Comments

You can add multiple lined comments in one of two ways. You can use // to preface the comment and then at the end of the comment press the Shift-Enter key combination, and do this on several lines.  Alternately, you can use /* at the beginning of the first line and then */ at the end of the last line of the comment.  When you want to go to a new line press the Shift-Enter key combination.