The Art of Code Writing in CRM Analytics

Image write-up source: https://www.facebook.com/theartofcoding/

In all the previous blogs, we have learned how to code, and make better dashboards, recipes/dataflows, and the like! But, we never really spoke about how to make our codes better!

What do we mean by better? Better is a subjective term — what we mean is the code we write should be easy to read, understandable to us now and our future selves, and the people coming after us who would have to read these codes and of course debug!

And I will start with a caveat that there maybe other things that you like doing that are not part of this post. Please let us know in the comments what else you do in this respect.

Code writing is an art! And this art like any painting or pottery or design varies from person to person. But, ultimately it boils down to some general points that we should all adhere to. In this blog, we will however stick to CRM Analytics!

Do’s and Dont’s

• The code should be easy to read and understand! The idea is to reduce the time it would take someone else to understand what the code says and not just the person who initially wrote it.
• The code should be manageable/maintainable.
• Is shorter code better? Not always! This depends on the situation. The ultimate goal should be easy to understand, manageable/maintainable, and of course, efficient!
• Names! The names of the steps/queries should be self-evident about what they are for without being too long to read. Imagine a dashboard that has steps like lens_1, lens_2, lens_3, and so on vs product_list, account_name, created_date, etc.
• Don’t name steps/queries/datasets etc. with generic names like lens_1, lens_2, clone_of_lens_1, etc.
• Continuing with names… Every organization or person should have a naming convention guide. Say, we write everything in lower case with an underscore in between the words (easiest to read) or we write in camel case. Whatever, it is, sticking to the convention, and following it makes it easy to write the next step/query in a dashboard or even name a dataset!
• Don’t start the names with numbers. Most languages would like to have at least one alphabet before the number!
• Use layouts (we use JSON which does it for us in the backend) that are aesthetically pleasing to the eye. No one would like to read a code that runs page after page with no breaks — it should not be painful to the eye and human mind!
• If we have a compact (non-SAQL) code that has the same 4 filters used in multiple steps, then place those filters in the same order instead of flip-flopping them!
• Comments! Yes, SAQL lets us comment on our code. It is very useful when we write a complicated query. For a simple query where we are just grouping by a few fields to find the amount is not a case for commenting, though. Choose when to comment wisely.
• The comments should be precise and compact — not paragraphs! For that, we can use documentation.
• Add a line \n after each statement. This serves a few purposes. If we want to comment out one statement, we can instead of the whole query. And when we take this code to an editor like Sublime or VS Code, we can break the code into multiple lines with ease! That makes it easier to read and edit
• Talking about editors, it is preferable to use VS Code or Sublime Text editors because they make it easy to edit and read the code instead of in CRMA backend. Especially, if the code is long with case statements and interactions/bindings
• Large calculations — Ideally break it down into parts because the next person who reads the code will be able to make sense of it more easily than a very long calculation.
• Stream names in a query — When using multiple streams, name those for what they represent similar to how we name steps/queries. This will help understand which stream is used where and why. And also, keep the code readable. Instead of q_A or q1 etc., use q_prod_2020 or q_acct_all representing the first one representing the product for 2020 and the second one representing all accounts.
• If there are intermediate results that should not be part of the final query, hide them! The last foreach statement should remove these intermediate columns. That keeps the code clean.
• Filter using hidden steps — There can be cases where we would like to filter the widget based on some other result-based criterion. A good way would be to use hidden steps. And then use this hidden step as a filter for the actual widget query.
• Query field aliases — Every column or field in a query should have a name that is again readable without being too long. A good example for a measure column would be “Total Amount” instead of “Amount”. When we say “Amount”, it does not specify what it represents, sum, avg, max, min, etc.
• Don’t bring in unnecessary fields to groups or measure columns. That just clutters the code. If we know that we ultimately need to group by Account Name but that is based on individual product costs, using the product id instead of the name or using the name and the id works better because we will be dropping both these columns in a later statement.
• Remember nulls — they make and break codes. If there is a null in a field that we are grouping by, any measure that is associated with that row may not pull in. Ideally, any field that we may want to group by should have a default value in the recipe/dataflow.
• Do not make streams or fields/columns with function names like sum, generate, full, etc.
• Keep the stream names as consistent as possible throughout the dashboard. This helps in decoding errors. If we have 3 queries that all have 3 streams for products filtered to 3 years, naming them prod_cy, prod_ly, prod_2y_ago would make sense.
• When naming nodes in recipes and dataflows, also follow a convention. Say, every node starts with what the node is for like Filter, Transform, Join, etc. Then follow this by filtering on which node or what is it filtered on. For transform, which node it is being filtered on? For Join, what is the left node, and what is the right node?
• The code we write should be reusable if need be. This helps us reduce the time taken to build a new dashboard. And thus makes our code scalable. This does not have to be the whole dashboard or query. Even parts of the query or interactions/binding can be usable in multiple other widgets and dashboards.
• Maintain consistency of dashboards with conditional formatting. If we say an absolute value of change < 25% is green and above that is red, then follow this convention in all related dashboards and widgets. This makes it easier for the user to understand without constantly referring to the legends.
• Don’t clutter a tab in a dashboard. Make it pleasing to the eyes of the user. Use multiple pages or components to make them better and easy to understand and read.
• Dashboard widgets should follow a pattern — start with the highest level and slowly drill down as the tabs/pages go by. The reverse is not a great idea unless there is a compelling reason to have the drilled-down version of the widget first.
• Dashboards are stories — how elegant and easy it is to read that story, is the nature of the work we do.
• Documentation — Documenting what the dashboard shows and how to use it as a user helps the user understand the details. But, this should not run into pages because then the user may lose interest. If the documentation genuinely needs to be long, then turn it into a video!

There are definitely more do’s and don’ts than listed here. But this should be a good start to writing better codes and making better dashboards and recipes/dataflows.