Any good rule writing convention for easy readability?

[comma]

I believe some of you people tend to follow a certain convention / standard in writing your Rules. So, I'm just wondering maybe some of you can share it here.
Because I found it hard to read and trace a very long Rule, especially the one with a lot of IFs, and I would like to adopt any good writing convention from you.
So, please do tell, how do you write your rules? How do you write IFs? How do you write your DB functions?

Also, which one do you prefer, the basic Rule Editor or the advanced one? Why?
Thanks for sharing.

[Alan Kirk]

I believe some of you people tend to follow a certain convention / standard in writing your Rules. So, I'm just wondering maybe some of you can share it here.
Because I found it hard to read and trace a very long Rule, especially the one with a lot of IFs, and I would like to adopt any good writing convention from you.
So, please do tell, how do you write your rules? How do you write IFs? How do you write your DB functions?

Also, which one do you prefer, the basic Rule Editor or the advanced one? Why?

I prefer the fundamentalist rules editor; .xru sheets. Why? They give me all of the formatting flexibility available in Excel, and also allow me to generate similar, repetitive code by using Excel string formulas. Also they're nice and easy to save if I'm not ready to try to save the rules into the system yet. Granted they don't try to generate syntax for you, but I've been doing this for so long now that it's not really a concern. (Although the fact that I have been doing so may be a concern in itself...)

I use a specifically formatted header block on top of each rule to help me identify them more easily; yellow background, bold black text, not that it matters what's chosen. The next cell down is in pale yellow, right aligned, and gives information about the feeders for the rule. That's followed by general commentary about the rule's propose and date of creation /update.

For simple Ifs I'll stick to one liners, but if it's a complex rule, especially with nested Ifs, I'll typically break it up so that I'll have:

Code: Select all

If
   ( 
     Test Condition
     ,
     True Result
     ,
     False Result
   );

The cell containing the commas denoting the start of the True condition have a blue background, and those denoting the start of a False condition have a red background. The indenting help me scan down to get a view of each statement.

If a db function is simple it will also go on one line; if it contains evaluated blocks I'll be likely to break it up as well.

Where I think it's necessary I'll also put a comment line indicating what the arguments of the Db formula represent. In many cases this may be nothing more than the "user friendly" alias of the element names.

But as with many things in TM1, there's no right or wrong answer, nor even a "best practice".

(Though of course we know that if there was, then using .xrus would be it )

[kpk]

An additional advantage of xru approach: it helps the versioning very much.
You can copy a new sheet (eg. with the date and/or version as the sheet name) to make changes on that.
It is easy to go back to an earlier version.
Also you can use the B column for many purposes eg. to link rules and feeders.

NOTE: if you choose xru, then be sure that nobody will edit the same rule via the rule editor!

[comma]

OK, both of you have convinced me that using xru is much easier, especially the highlight feature mentioned by Alan (maybe it's just me who's dumb, but it never even crossed my mind!).
However, the TM1 model I have on hand now was built using classic Rule Editor. Is it possible to convert it to xru format? If it is, how?

And while I'm on it, if you guys were to be given a new and already completed TM1 model, how will you try to understand it? Do you explore every Rules, every Dimension Attributes, and every TI processes? And will you use top-down or bottom-up approach (summary-cube-to-input-cube OR input-cube-to-summary-cube)?
Because this is what happened to me, and it's killing me trying to understand this model.

And to reply Alan's post, isn't breaking the rules on every statements and commas going to be confusing, especially when it's nested and combined with a lot of DB functions? If you don't mind, could you post a print screen of your already formatted rule here? I'd like to see it.

[Alan Kirk]

OK, both of you have convinced me that using xru is much easier, especially the highlight feature mentioned by Alan (maybe it's just me who's dumb, but it never even crossed my mind!).
However, the TM1 model I have on hand now was built using classic Rule Editor. Is it possible to convert it to xru format? If it is, how?

Easy. Just go to the TM1 -> Rule Worksheets -> New... menu in Excel, and create a sheet for the desired cube. That will create a blank .xru.Go to the Rules Editor, copy the content and paste it into the blank rules worksheet. You may want to pre-format Column A as text. That's a precaution against there being rule lines which consist of something which Excel converts into either a value or a date. Excel likes to "help" that way.

And while I'm on it, if you guys were to be given a new and already completed TM1 model, how will you try to understand it? Do you explore every Rules, every Dimension Attributes, and every TI processes? And will you use top-down or bottom-up approach (summary-cube-to-input-cube OR input-cube-to-summary-cube)?
Because this is what happened to me, and it's killing me trying to understand this model.

Yeah, that's a tough one. Unfortunately there's no single good answer for it; the best approach will vary from model to model. The last time I had something like that I found the final output cubes and worked backwards, making notes along the way. It was complicated by the fact that some of the cubes that had end outputs also had inputs so it wasn't strictly linear. However I found that it wasn't necessary to understand the model in its entirety before I could start to get a "feel" for how it hung together. While I still maintain that there's no "one size fits all" approach I think that generally working back from outputs is the easier way. If you work from the inputs you won't necessarily know where they go, but if you work back from the outputs, well, you know that they have to come from somewhere.

However before doing that my usual approach would be to document the cubes; use the TabDim worksheet function to list the dimensions of each cube in a workbook, then set about making a short commentary (and I mean short, otherwise you'll just get overwhelmed in the detail) for yourself about what each dim represents, and what each cube stores. The second thing I'd do is to read through the TIs so that I knew where data was flowing from and to. After that I'd start on the rules.

And to reply Alan's post, isn't breaking the rules on every statements and commas going to be confusing, especially when it's nested and combined with a lot of DB functions? If you don't mind, could you post a print screen of your already formatted rule here? I'd like to see it.

Yyyyeaaah, might be some confidentiality issues there. I run the model but I don't own it, the company does. However you may have misunderstood me. I don't break down every function on its argument commas, I generally only do that with If functions. And the reason that I do that is so that I can look at a single, discreet block of code (the True block, and the False block) by indenting level, and by whether it appears under a Blue (true) comma or Red (False) comma. This prevents the all too easy mistake (particularly in nested If blocks) of continuing to read code that actually occurs after a block has ended, by missing a closing bracket, for instance. It would be rare for me to break up a DB() function into multiple lines, though, even if it had another function embedded inside it as an argument. For a complex rule I'll generally have one function, constant or operator per line, though if it's a simple expression I may still have it on a single line. I'll see whether I can find one of the sample databases which has a rule that I can break up, and demonstrate it there.

[lotsaram]

However, the TM1 model I have on hand now was built using classic Rule Editor. Is it possible to convert it to xru format? If it is, how?

Easy. Copy/Paste

However, I wouldn't necessarily roll over and switch to XRU just like that. I'd say one of the main reasons Alan and Peter use XRUs is habit, they have been using TM1 for a long time, when they started with TM1 XRU sheets were the only UI to edit rules and old habits die hard. Don't get me wrong, I also use XRUs (quite often in fact) but in specific cases where the benefits of XRUs are significant - the main ones IMO being very easy version control and switching rules on and off during development & testing. Using formula parsing in Excel to generate repetitive blocks of rule code for you, while possible, is something done very rarely in practice, I wouldn't count it as a major advantage. For someone not yet expert with TM1 rules I believe the advanced rule editor has a lot of advantages with automatic code colourisation, function prompting and picking. It certainly makes rules easier to learn and write. (The old rule editor on the other hand in my opinion offers absolutely no advantages over XRUs.) One caveat the new rules editor was very buggy in 9.1 and I wouldn't recommend it, however in 9.4 and 9.5 most of the issues have been resolved and it is quite usable.

If you don't mind, could you post a print screen of your already formatted rule here? I'd like to see it.

Here's a very simple totally generic example so no issues of commercial confidentiality. Assuming a dimension with a single hierarchy the following rule will "cascade" element security from a parent to all descendants. It's a very simple example but it basically follows the rule coding conventions Alan was talking about, the conventions I use are very similar.

Code: Select all

## Cascade security, apply the parent's security settings to all children
[ ]  = S:
IF( DB('}ElementSecurity_myDimension', ELPAR('myDimension', !myDimension, 1), !}Groups) @= '',
  STET,
  DB('}ElementSecurity_myDimension', ELPAR('myDimension', !myDimension, 1), !}Groups)
);

[Alan Kirk]

However, the TM1 model I have on hand now was built using classic Rule Editor. Is it possible to convert it to xru format? If it is, how?

Easy. Copy/Paste

However, I wouldn't necessarily roll over and switch to XRU just like that. I'd say one of the main reasons Alan and Peter use XRUs is habit,

Oh, you would say, would you? The main reasons that I use them are the reasons that I say that I use them. Reasons which I've detailed on multiple occasions before this, and don't plan to repeat here. If I see an advantage in moving to something new, I move to it, habit or not. I don't see more advantages with the rules editor than I do with .xrus, and consequently that, and that alone, is the reason that I continue to use .xrus.

I can't speak for Peter, but I'll thank no-one to ascribe motives to me that aren't mine, especially when I've made my position quite plain on multiple occasions.

they have been using TM1 for a long time, when they started with TM1 XRU sheets were the only UI to edit rules and old habits die hard. Don't get me wrong, I also use XRUs (quite often in fact) but in specific cases where the benefits of XRUs are significant - the main ones IMO being very easy version control and switching rules on and off during development & testing. Using formula parsing in Excel to generate repetitive blocks of rule code for you, while possible, is something done very rarely in practice,

Not by me it ain't. Whether other people chose to avail themselves of the functionality is their call.

If you don't mind, could you post a print screen of your already formatted rule here? I'd like to see it.

Here's a very simple totally generic example so no issues of commercial confidentiality. Assuming a dimension with a single hierarchy the following rule will "cascade" element security from a parent to all descendants. It's a very simple example but it basically follows the rule coding conventions Alan was talking about, the conventions I use are very similar.

Code: Select all

## Cascade security, apply the parent's security settings to all children
[ ]  = S:
IF( DB('}ElementSecurity_myDimension', ELPAR('myDimension', !myDimension, 1), !}Groups) @= '',
  STET,
  DB('}ElementSecurity_myDimension', ELPAR('myDimension', !myDimension, 1), !}Groups)
);

That follows the convention that I was talking about, does it? Wow, that's odd. Because I thought that my convention would have the commas on separate lines so that they clearly delimited each True or False block of code. Which may not make a difference when the blocks are one liners as they are here, but is considerably more useful when the code runs to multiple lines, especially when there are further nested conditions.

But hey, maybe I didn't mean what I said I meant. That happens, or so I'm told.

[lotsaram]

Alan - I for one appreciate the odd healthy debate here and there. It's enriching and life would be boring without some differences of opinion.

I didn't say the convention I used was the same, only similar. I'm sure you understand the distinction. Although I am very careful and finicky with indenting to make separate true, false blocks and nested statements easy to discern (and occasional true/false font colour blocks when using XRUs with a larger than normal degree of nesting) and I am careful to close each IF with a bracket on a separate line with appropriate indenting, personally I don't care for placing the comma separators by themselves on separate rows. Each to their own, the importance of coding conventions is not so much what convention to adopt as long as one is adopted and adopted consistently within a given implementation.

Alan may not be swayed by habit but most people are. The main point I wanted to make is that people reading this thread shouldn't jump to conclusions that XRUs are better in all instances for all people. For anyone who is already expert in TM1 rules it is true the advanced rules editor offers little benefit, however that's not the case for newer TM1 practitioners where function picking, hover help and code formatting do offer some real tangible advantages in ease of use and lowering the gradient of the learning curve.

I can see the advantages of each editor. I would be profoundly unhappy if support for XRU (or XDI) worksheets was ever removed as I use them extensively. But I also use the advanced rules editor a lot, it has some nice features that you don't get in a spreadsheet and it has it's place too.

[paulsimon]

lotsaram

I have been writing TM1 Rules for 12 years. I use the old Rule Editor over XRUs largely because of the ease of editing rules as it is often necessary to split rules over multiple lines which is a pain to do in Excel.

I have been in to client sites where they have used XRUs which tends to mean that long complex rules all appear on one line which makes them very difficult to understand.

I have also had too many situations where XRUs and XDIs have got out of step with the source system as it is too easy for someone to edit the rules/dimension directly, then the next change in the XRU / XDI wipes out the previous change. It needs a lot of discipline to only use XDI or XRU. The other issue is around the need to always check that the Local Data Directory is mapped to the correct location, otherwise you can end up picking up an old XRU or XDI with similarly disasterous results.

Of course all the above issues can be resolved with a disciplined approach. It isn't impossible to do indentation in Excel, just harder.

Similarly if you do use the Rule Editor, it is still possible to use a versioning tool like Source Safe on the .RUXs.

If I could, I would use the new SyncFusion Rule Editor, because the colour coding, function look up etc are potentially useful. Unfortunately it still falls down on the ability to easily enter DB formulae which is a major area of rule writing. I hope that version 10 will fix this, or replace the SyncFusion rule editor with something new altogether.

Regards


Paul Simon

[Alan Kirk]

I didn't say the convention I used was the same, only similar. I'm sure you understand the distinction.

Quite. Dogs and cows are "similar" in that they both have four legs. Only a few key characteristics are different.

In this case the use of separate, distinct lines to demarcate the start of true and false code blocks which, given that the topic at hand is formatting, could only ever be a minor difference.

Of barely any significance at all, really.

Alan - I for one appreciate the odd healthy debate here and there. It's enriching and life would be boring without some differences of opinion.

You seem to have missed the key point in the previous post so let me explain it to you so that you "understand the distinction".

You DO get to argue the merits and drawbacks of a particular piece of technology, and indeed I was surprised that no-one had done so with regard to the rules editor earlier. You do NOT, however, get to argue the reasons for particular specific individuals choosing or not choosing to use that technology. You are especially not entitled to argue that point when it carries an implication, whether intended or merely thoughtless, that the reason that those specific individuals don't use the technology is because that they've been doing a job for so long that they're stuck in a rut and just can't be bothered to embrace the Latest! And! Greatest! technology, as defined by one consultant (i.e., you). And you particularly do not get to do that when those individuals have made it clear that they are using the older technology when they've tried the newer one, and hold the opinion that the older one works better for specific purposes.

Because then, if someone were to come along and read the thread later on, they may get the impression that those specific, named individuals aren't up to being employed where cutting edge implementations are needed.

Understanding the distinction now, are we? Because I can explain it to you more graphically if you want. If you want to make over-generalisations like " Alan may not be swayed by habit but most people are", knock yourself out. After all, many if not most people do have routines and habits, that could hardly be argued. Whether professionals as a class are more swayed by habit than by adopting newer or better practices to do their job better... well, that's a lot more debatable.

Whether two specific, named professionals are restricted more by habit than by a willingness to adopt better techniques, well... you know that line you have to be very wary of crossing when making statements in a public forum?

Look down. Right under your toes.

Might be an idea to keep your opinions to the tools, not to the people who are using the tools.

I follow the principle that Chris Orwig (another photographer) follows. "I don't care whether it's newer, I only care whether it's better". For a newbie who is learning rules, yes, the rules editor is far and away the better tool. That wasn't the question. The question was about implementing and documenting rules in an existing system and I still hold to the opinion (for the reasons that I say, not the reason that you say), the absolute formatting flexibility that .xrus offer make it the better tool which is why I'll continue using it until or unless a rules editor which I consider offers better value arrives.

[Alan Kirk]

I have been writing TM1 Rules for 12 years. I use the old Rule Editor over XRUs largely because of the ease of editing rules as it is often necessary to split rules over multiple lines which is a pain to do in Excel.

Can you explain that? In Excel, if you want a new line, you drop down to the next cell. I'm genuinely unclear on how that's "a pain".

I have been in to client sites where they have used XRUs which tends to mean that long complex rules all appear on one line which makes them very difficult to understand.

Again, I'm not seeing why this is something particular to xrus. You either split rules up or you don't, regardless of the environment that you create them in.

I have also had too many situations where XRUs and XDIs have got out of step with the source system as it is too easy for someone to edit the rules/dimension directly, then the next change in the XRU / XDI wipes out the previous change. It needs a lot of discipline to only use XDI or XRU.

The other issue is around the need to always check that the Local Data Directory is mapped to the correct location, otherwise you can end up picking up an old XRU or XDI with similarly disasterous results.

Of course all the above issues can be resolved with a disciplined approach.

I'm not sure why it would take a LOT of discipline. You make a choice, you stick with it. What you're describing goes beyond merely "undisciplined".

It isn't impossible to do indentation in Excel, just harder.

Again, how are you figuring this, given the presence of the Increase Indent and Decrease Indent buttons on the Formatting toolbar?

Similarly if you do use the Rule Editor, it is still possible to use a versioning tool like Source Safe on the .RUXs.

And remembering to use an external tool to handle your versioning wouldn't require a lot of discipline?

[LoadzaGrunt]

In Excel, if you want a new line, you drop down to the next cell. I'm genuinely unclear on how that's "a pain".

Well, take for example a rule like this:

Code: Select all

['Measure']=N:DB('SomeCube',!Dim1,'SpecificElement',!Dim2,!Dim3);

Now, for arguments sake, let's say I want to break the rule up like this:

Code: Select all

['Measure']=N:DB('SomeCube',!Dim1,
'SpecificElement',!Dim2,!Dim3);

If I did those two lines in two cells in Excel then the second cell would knock off the apostrophe of my string literal reference as Excel would assume it was the escape character that often indicates that you want a number to be recognised as text. That bugs the hell out of me.

Don't get me wrong, I like XRUs but nowadays I use the Advanced Rules Editor.

In repsonse to the OP's question: the convention that you should always follow for easy readability is to comment the hell out of your rules

[Alan Kirk]

In Excel, if you want a new line, you drop down to the next cell. I'm genuinely unclear on how that's "a pain".

Well, take for example a rule like this:

Code: Select all

['Measure']=N:DB('SomeCube',!Dim1,'SpecificElement',!Dim2,!Dim3);

Now, for arguments sake, let's say I want to break the rule up like this:

Code: Select all

['Measure']=N:DB('SomeCube',!Dim1,
'SpecificElement',!Dim2,!Dim3);

If I did those two lines in two cells in Excel then the second cell would knock off the apostrophe of my string literal reference as Excel would assume it was the escape character that often indicates that you want a number to be recognised as text. That bugs the hell out of me.

I'll give you that one but I can't think of an instance of where I'd do /have done that. Breaking up a function in that way would actually make it less readable to me; with the exception of If()s which are a special case IMHO, I don't like to break up single functions if I can avoid it. But I realise that it's an example only and there may be other instances where you may lead with a constant string. Possibly I've been using Excel for too long but I'm just in the habit of whacking in a double single quote if I know that I need one as the first character, even in a sheet which is unrelated to TM1.

I'd call it a "niggle" more than a "pain".

Don't get me wrong, I like XRUs but nowadays I use the Advanced Rules Editor.

In repsonse to the OP's question: the convention that you should always follow for easy readability is to comment the hell out of your rules

Amen to that one, with special emphasis on where the feeders are. (Especially if they're in a different cube.)