What to look for in a (Blue Prism) code review

So here you are. After weeks of painful and confusing perusal of Blue Prism Foundation Training and guides, after months of back-to-back development projects, after days of reviewing all Blue Prism documents again and passing that certification exam, you feel you finally got it. Blue Prism becomes your second nature. All the functions and features are at the tip of your…hands. Your hands drag and drop while your mind formulates the logics. Your diagram looks organized and your process page looks clean. In one moment, your mind can run through highest scheme of the process like a hawk watching from above. In another moment, it can zoom in to estimate the values of each variable like a watchmaker examining his craft. You felt ease. You felt mastery. You felt accomplished.

Your boss is so happy with you. Then one day she approached and told you your job now is to review other codes and mentor other team members. You are ecstatic. The next day, first thing in the morning, you ventured out of your work folder and peeked into others. And your jaw dropped as your heart sank the moment you opened up the codes. It had been just few minutes of tabbing through the pages, you already hear you screaming WTF more than once. What are you gonna do? Bullet-point every single errors sound too much work. Holding the bible of “Blue Prism Development Best Practices” and preaching doesn’t sound like you. Come back to where you were yesterday doesn’t sound good, either.

Often in the absence of clear guidelines or procedures, in the shortage of time, and in the middle of panic, you look for a good starting point to systematically review the code. Leaving the gritty-nitty details of each process requirements aside, you want to start from the big things and the important things first. Those are layout, exception handling and consistency level. Just like you wouldn’t see an athlete without a strong core, I have not yet seen any good configuration lacking in those aspects. “All happy families are alike,” Leo Tolstoy opened his novel Karenina with this line, “each unhappy family is unhappy in its own way.” I relate to programming with a similar view – all good code are alike; each bad code is bad in its own way.

Following are some ideas about where to look at:

Judge the design against Blue Prism templates

Blue Prism provides user with a standard process template. The company even encourages users to follow the layout of this template in their configuration because the template includes most of the points covered in Development Best Practices. Of course, molding every single process into the template would be unfit. However, most team will adopt a certain extent of the template into their practice. If you have the best version of your team practice, use that instead. If not, the template is the great place to start. On a side note, the template is worth every minute of your time spent to understand it inside out.

Once the template or best version of your team is in your blood, you would be able to spot out the deviations right away. Hold on that temptation to call out and request for changes. Instead, note down the deviations as you drill through the codes from the Main Page to each lower-level sub-pages. By the end of this exercise, you should have a list of all deviations. At this point, make sure you step away from the work you have done to have a realistic view of possible outcomes. If you push back, how many of these deviations would be addressed? How do you convince the team to change? How much time do you have before the deadline?

If you prefer to be meticulous and vigilant, rank the deviations by level of severity and group them by topics. It helps keeping track of and communicating the issues.

Gauge the strengths of exception handling

Exception handling is the first and last line of defense when things go wrong. In my first few months of learning to program, it is the topic I least know about. In most development projects, it is the last thing developers are worried about. So exception handling is like the extra mile an athlete goes on top of the mandatory training; the strength of exception handling often tells how much above and beyond a developer goes for his own work.

Although what constitutes a strong exception handling deserve another separate discussion, there are several basic questions to ask if the exception handling does its job. Will exception type and details thrown at the lower level eventually be caught and provide useful information about the errors? Will the exceptions – wherever they can possibly occur – interrupt the least possible the flow of working the next cases? Is the developer making clear, separate handling paths for different types of exception: Business Exceptions, System Exceptions and System Exceptions – Try Once?

 Examine the quality of the looks

Similar to what William Zinsser - a lifelong journalist, contributor of American leading magazines, teacher of writing  - wrote about relationship between thinking and writing in On Writing Well: “Clear thinking becomes clear writing; one can’t exist without the other”, the visual aspects have direct relationship to the quality of the codes. Unlike other text-based programming language, Blue Prism is diagram-based programming. Therefore, the visual elements can be a strong indicator of developer’s thinking quality. Those visual elements can be further divided into smaller topics such as layout, naming and choice of abstraction.

Layout is about how the arrangement of diagrams supports the code understandability. Colors and fonts are just icing on the cake. The essence of a good layout is about a good sense of proportion and symmetry, of flow, divergence and convergence. Let’s examine some examples of good layout versus bad layout.

While good layout helps developers able to quickly identify the potential areas of bugs, good naming helps zoning in the details much easier. In Clean Code, there is a devoted section about naming convention. In my own practice, I tend to name the pages, stages and action other than Main Page with the follow structure: [Verb] + [Noun]. For variables, I name it [Identifier] + [Nouns]. Just good naming alone can reduce greatly the need for code comments – if code comments are even practiced in your team.

Choice of abstraction is a more abstract and subjective topic so I would only look for consistency as an indicator of quality. In another word, I ask this question: how consistent is the developers’ interpretation of Single Responsibility Principle? In context of Blue Prism, that principle is simply that every page should have responsibility over a logical unit of the process and that responsibility should be entirely encapsulated by the page.

As always, software development is a work in process, a craft in the formation. Rarely anyone – if there is – would be able to get all the aspects of exception handling, layout, naming and choice of abstraction right at the first time. Developers get it right by revisiting their works and improving upon it. William Zinsser wrote in his classics On Writing Well: “Rewriting is the essence of writing well; it’s where the game is won or lost.” Perhaps writing codes is not an exception.