In the world of XPLAN, template code is written predominantly in XMERGE, a variant of Python.
During the early part of my years as an XMERGE programmer, I’d wade through pages and pages of code trying to understand why my code didn’t work the way I expected. Mistakes are part of the programming process. Even the long-time programming pros make significant mistakes over the course of their career. But most of those mistakes could be avoided with proper coding habits or at least breaking the bad ones.
Breaking bad habits is hard especially if you don’t realise what you are doing is undermining your own work. But, if you follow some simple ideas, you and any programmers who comes after you will get more done with less hassle and rework. So, in the interest of helping the XPLAN coding community, here is my top five programming confessions and my advice on how you can avoid them.
Confession #1: I often rushed in without enough planning
Building a template requires planning. No matter what type of document you are coding, chances are you will need to integrate logos, adviser and licensee details, coded content, data from modules etc, all in a format that follows one or several business style guides. These most likely needing to be conditioned based on wizard parameters.
Quality software solutions cannot be designed easily and off the top of your head. Quality XPLAN solutions are no exception.
Think about architecture and have a plan.
What is the user experience? .,..is a wizard necessary? …are multiple licensees using this XPLAN site? Where are the branding details drawn from? ….are there sections that are specific for each licensee or practice?….Where (location) will the templates reside?….Who needs access to them?…Will they require regular updates?…Does anyone else in your team need to be able to support and maintain them?
Perhaps you’ll also need to consider some non-technical issues as you guide the site owner through these decisions. For example…Is the site owner interested in organising the workload into phases that will deliver a minimum viable product in the foreseeable future?
Personally, I like to build flexibility in my solution in case I need to change parameters in the future but especially to make the bug fixing process easier. The key to adding the extra flexibility into your solution is to understand well enough the architecture of XPLAN and how you can leverage field definitions, the document library, wizards and templates in your design by breaking down big pieces into smaller components that you can test, replace, update and debug.
While writing code without planning might work for a small letter template, it will have a counterproductive effect on larger document templates such as an SOA that has a myriad of output combinations coded over hundreds of pages. A small mistake can compromise the entire document.
Remember that WORD is not a well-structured development environment. It can quickly become challenging to keep track of the overall template structure. The original design can eventually start to reveal problems. At this point you might find yourself cycling back to re-architect your solution.
Importantly, do not get stuck looking for the perfect solution. You only need a plan to get you started and to give you a pretty clear view as to how you will design your template and how it will fit within your solution.
Confession #2: Don’t assume that if your template works, then things are right
One thing you must have noticed with XMERGE is that most of the time mistakes in the smallest places cause templates to fail and then leave you at a loss for what’s gone wrong in it.
For example, take a look at the following two pieces of code. Is there anything wrong with it?
Example #1:
<:if $parnter:><:=$partner.title:> <:=$partner.preferred_name:> <:=$partner.last_name:><:end:>
Example #2:
<:let myVariable = 10:><:for i in range(0, myVar, 1):><:=i:><:end:>
Both examples merge without errors. Life is good. However both examples have coding errors.
One way you can remediate to that is to turn on the Debugging Mode option in your report template settings by following those simple instructions available from the IRESS Insights Community (note: you will need a login): Set a template to Debugging Mode
While the debugging mode will show an error in the second example the first example will still merge through without throwing an error.
The problem with the code in the first example is the typo in the primitive “$partner”. It correctly handles the case where there is no partner but it is still incorrect. This error is an exception though as the debugging mode is designed to throw an error when a if or for statement fails. However this highlights the importance of writing tests.
Even expert programmers don’t write code without tests.
Every ‘if’ condition statement is a logic branch that requires to be double tested. If you are running the template of a scenario wizard, create test scenarios to cover off most of the testing across your template.
By the way, errors are a good thing. If seeing these Err: Handling <:if:> ..details=yellow highlighted error messages bother you, you need to change your mindset to look at them as helpers. They mean you are making progress.
Confession #3: I used to somehow make existing templates worse
Programming is often about reading existing code, finding what is required and integrating changes into a current solution; Whether you are getting inspired from existing templates or inheriting someone else’s work, always make sure to leave the template cleaner than when you started to work with it. Here are a few wrong practices that usually make a template messier:
- Duplicating code. If you duplicate a code section to only change a line, chances are you could have simply factorised the common part into variables or a sub-template or a set of functions that you could reuse throughout your template. Always keep the concept of refactoring in your mind to reduce the risk of introducing errors and improve code readability.
- Hardwiring. If you need to use a value that can change in different environments or at different times, most likely you would want to have this value as a parameter in the XPLAN interface rather than hardwired into your code.
- Writing obvious comments. Generally speaking when it comes to commenting, often less is more. While IRESS have allowed for some time the ability to insert comments into a template (<:# this is a comment :>) which is a wonderful thing. Try to avoid writing comments when you can replace it with better-name variable. Longer variable names mix documentation into the code. This documentation follows the variable everywhere it’s used, unlike comments, which are only attached to the declaration.
- Underestimating code quality. One of your most important jobs as a programmer is to clearly convey the implementation of a solution you are developing. Even the small things matter. For example, highlighting open/close tags with the same color. <:if $partner:> Write this <:end:>
- Using sloppy workarounds. Being in a hurry (and who isn’t?) is one thing, being sloppy is another. If you are in the zone and you using shortcuts to get the work out, then your good programmer conscience must ensure you to come back and clean it up later.
Confession #4: I rarely asked for help
So many times I wasted precious time trying to figure out how to do something, when I should have just researched it first or asked someone for help.
When you run into a problem, chances are someone else ran into the same problem and found a solution for it. Save yourself some time and research the IRESS Insights Community or contact XPLAN support or PlanFocus… We’ll gladly help you out.
Smart programmers reuse code as often as they can. By leveraging existing code, you’ll save hours of work. Remember that using someone else’s work can also introduce problems into your template if you haven’t done a thorough review of it first. Never assume that a passage of code is good since it seems to be solving your problem. Research the code and try to understand everything about it.
Confession #5: Give myself a break? Never!
If you are like me, a lot of your breakthroughs happen when you are not in front of the computer. The reason is that while you are still thinking about the problem at hand you are thinking about it as a whole rather than being distracted by technical details in front of you. I find that if I go for a coffee and come back I am often able to attack a problem in new ways than if I just stared at the screen waiting for inspiration to come.
That said taking breaks is not just about boosting your productivity or creativity, it’s also about preserving your health, and that’s not something you want to compromise. As a programmer you’ll often be in the zone for hours, losing track of time, drinking lots of coffee and no water, staring at a screen until your eyes feel like you rinsed them with sand.
As a rule of thumb, code for 45 minutes and then have a 5 to 10 minute break. Not only will this prevent you from developing all sorts of pains due to excessive use of keyboard and caffeine, but it’ll also help you increase your productivity significantly.
Bottom line
I have one final confession to make: I sometimes still make these mistakes today, we are all human.
As developers we have to wear many hats: analyst, designer, programmer, tester, documenter and support technician but the good news is, we don’t have to be an expert in all those areas to achieve great results. You don’t need to know the advanced XMERGE syntax if you know how to research the IRESS Insights Community or ask XPLAN professionals;
The bottom line is there are many ways to design templates to fit into a solution. If you keep some basic principles in mind you won’t need to be an expert XMERGE programmer to get the job done and as you find a path around challenges you will define guidelines of your own.
At PlanFocus, we create unique hand-crafted XPLAN sites that deliver your advice brand and use XPLAN to its full potential. If you would like help with programming with XMERGE or want to learn more about our services, please get in touch.
