Comment Your Calcs

I’m sure there are plenty of blog posts out there about using comments in Tableau, but I’m going to write another one, just to share my perspective. Granted, comments are not a sexy topic, but they can be really important. Plus, I promise this’ll be short.

In college, I studied computer science and I spent the first part of my career as a programmer. During school, my professors constantly talked about the importance of commenting code. In fact, it was often more important than the code actually working (this is likely the only reason I passed an assignment to build a B-Tree in C++). In their minds, code that worked, but couldn’t be understood by anyone other than the programmer, was completely useless. And, generally speaking, I tend to agree.

Why Comment?

Comments in code have lots of different purposes. You may use them to describe the intent of the code (what it is supposed to do), to act as pseudocode (particularly for complex code blocks), explain the algorithms or calculations being used, provide some high-level information about the code block as a whole, etc. But why should we comment our code? For me, there are two primary reasons.

First, you do not want to own this code forever. At some point in your career, you’re going to get promoted, move to a different project, or get a new job and someone else is going to need to take over the maintenance of your code. If you do a good job of commenting your code, then those comments will make it much easier for that new person to understand what you’ve done and why. And that translates to less of your time in knowledge transfer.

Second, you will eventually forget what the code does. If you’ve been away from a block of code for a while, it’s simply impossible to remember exactly what it does and why. In this case, comments are your best friend as they will be the guideposts which remind you of what you were thinking when you wrote the code. In my early career, I made this mistake a lot—I’d include minimal comments in a segment of code, only to return to the code a year or two later and have no idea what I was trying to do.

Tableau

So what does this have to do with Tableau? First of all, many of us write code outside of Tableau in order to shape our data, be it in Python or R or even VBA for Excel. If we ever want to share that code with others or wish to reuse it ourselves, it’s definitely a good idea to add some comments. But, in this post, I want to focus on Tableau.

One of the beauties of Tableau is that it doesn’t really require any coding. This makes the product accessible to a much broader audience of people who are not coders. But, there are some scripting aspects that canbenefit from comments, namely, Calculated Fields. Calculated fields are pretty much just small snippets of code. And, like normal code, comments can be extremely valuable.

Admittedly, despite my background, I don’t always do a good job of this myself. Take, for example, this calculated field from my Shapeshifting Tile Maps visualization:

  

In case it’s difficult to see the text in the screenshot, the calc’s full text is:

IF [CY] % 2 = 1 THEN [CX]+[Row Offset]+([Horizontal Padding]*([CX]+[Row Offset])) ELSE [CX]+([Horizontal Padding]*[CX]) END

This is a fairly short calculation and not terribly complex, but it’s highly likely that I’d be confused by it a year from now. So, let’s add some comments to help add clarification.

That’s definitely better. At this point, I haven’t given you any details on the purpose of this calculated field, but from the comments alone, you now have a pretty good idea of its intent.

But comments are only half the battle. The formatting of your code can also go a long way to help with readability.

As you can see, use of spacing, indents, and carriage returns can make a big difference.

Finally, we can add some additional inline comments to provide just a bit more information about what’s happening in each section.

And now we have a calculation that is much easier to read and understand than the original.

Wrap-Up

So, in summary, comments are your friend. By adding just a few comments here and there, you’ll be able to future-proof your calculations so that you’ll always understand them. And, equally important, others will be able to understand them as well, whether those people are taking ownership over something you’ve built or just downloading your Tableau Public workbook in order to learn from you. I guarantee they’ll be thankful for the comments.

Ken Flerlage, January 12, 2018

Twitter | LinkedIn| GitHub | Tableau Public