This blog series explores how applying a set of coding best practices can help reduce errors during model development. We’ve captured these practices in the acronym MATHS: Modularized, Archived, Tested, Honed, and Standardized. This post focuses on the Standardized element.
Consider this example, in a world with no standards of identity for food…
You just had a banner week. Your team completed a major milestone for a model development initiative. Your boss, normally one not to give praise, dropped not one but two compliments on you like manna bombs. You exercised every day and ate healthily. You need to celebrate.
You head over to the supermarket and pick up a pint of Peanut Butter and Chocolate Chip Cookie and Brownie crumble ice cream. You are so happy you decide to do a rendition of Michael Jackson’s first Moonwalk[1] on the way to checkout.
You get home, dump your stuff at the front door, and make a beeline to the kitchen. You grab a bowl, spoon, and ice cream scoop, pop the lid off your gallon of delight, and drop three large scoops of ice cream in the bowl. You dig in…
… and slowly chew what’s in your mouth, a frown forming. It’s “ice cream” in the sense that it is a scoopable frozen dessert, but it certainly doesn’t taste like ice cream. You look at the carton and it says it’s ice cream.
Curious, you look at the list of ingredients and see that goat’s milk is one of the first ingredients. You grimace. What the…shouldn’t this be identified as goat’s milk ice cream?! Had it been you would’ve never bought the dessert! Disgusted, you place the bowl into the sink, your high from the week melting into a puddle of confusion and disappointment[2].
Standards set expectations. When we buy ice cream, we expect the company to make it with cows’ milk not goats’ milk. When we buy goat milk ice cream, we expect the company to make it with goats’ milk, not cows’ milk.
What Does It Mean to Standardize Code?
The Standardized best practice at FRG is the process of incorporating into our code the criteria laid out in our coding standards. We created these standards to set expectations for code developers to:
- create high-quality modules,
- enforce consistency,
- facilitate collaboration,
- improve readability.
There is no “one size fits all” coding standard. Coding standards will not only change between programming languages, but they will also change from company to company. Whatever the coding standards are, though, the most important part of using them is to use them. And to use them consistently.
It is worth quickly mentioning code reviews. While code reviews are not a standard, they certainly are a best practice. Code reviews are when a tech lead or a peer reviews the code to surface logic problems or bugs. It is easier to perform reviews when the code aligns to the coding standards because the reviewer has a framework in mind.
How does the “Standardized” best practice reduce model risk?
Coding standards define criteria which improve the readability of code. This, in turn, helps ensure the module’s logic is accurate.
The remainder of the blog will describe two guidelines we have for comments and readability. These examples hopefully illustrate why code standards are important. If you are interested in knowing more, a quick web search or query to a chatbot will provide you with many guides.
For what it’s worth, while we have coding standards at FRG we have adopted many from the PEP 8 – Style Guide for Python Code and rely on that style guide for situations we haven’t covered in our own standards. We like PEP 8 because it is comprehensive, vetted by many, and, after SAS, Python is our second most used programming language.
Guidelines for Comments in Code
Adding comments to your code is a must. Comments provided context and explanation; comments make the code easier to understand.
We have two types of comments. If the script requires it, we will provide a “header comment.” We place this comment at the top of the code and include these sections:
- Name of script
- Ensures the header comment pertains to the script that it is in.
- Purpose
- Provides a high-level explanation as to what the code is doing.
- Notes
- Includes additional information that other developers or your future self might find helpful when working with the code.
- Development and maintenance history
- Shows, at a glance, who updated the code, when, and why.
The other type of comment is “within code comment.” We place these in the code where we believe additional information would help the code reader. For example, we would add a comment to explain a complex calculation that spans multiple lines.
Within code comments can span multiple lines and should precede the code it is explaining. We expect these comments to be:
- Complete sentences using proper case and punctation, divided into paragraphs if needed.
- Clear, succinct, and useful.
The last characteristic – useful – is particularly important. We have noticed that many junior programmers add comments for code that aren’t useful – it’s obvious from the code what is happening. An example of this in Python:
From the code, it is clear the data is being sorted by account id.
Lastly, make sure to maintain the comments. If the code changes the comments need to as well for the sake of consistency and readability.
Guidelines for Readability in Code
Speaking of readability, FRG also has some guidelines that pertain to this as well. Below are just a few, for the purpose of an illustration[3]:
- Each indent should be 4 spaces.
- Lines should not exceed 79 characters.
- Indent line breaks with an eye toward clarity.
Here is an example of SAS code without the above guidelines:
And here it is with guidelines for readability:
This is more readable because the code:
- Aligns the logic for the first IF statement.
- Sets apart the conditional IF statement (the second IF statement).
- Groups the ELSE statement of the first IF statement separately from the other logic.
Putting Best Practices into Practice
There is much more we could cover when discussing coding standards. We just described a couple to show the importance of the Standardized best practice.
As mentioned above, we encourage those who are interested to do their own investigation. If you find guidelines you like, pull them together in your own coding standards and embrace them. This will help reduce model risk by making the code readable which improves understanding of what is happening in the module. That helps the model developer and code reviewer ensure the code is doing what it is supposed to do.
Jonathan Leonardelli, FRM, Director of Business Analytics for FRG, leads the group responsible for business analytics, statistical modeling and machine learning development, documentation, and training. He has more than 20 years’ experience in the area of financial risk.
[2] Standards of Identify for Food – This was a surprising time suck, especially the labeling of cheeses.
[3] The first two examples align with the PEP 8 – Style Guide for Python Code; the last is a summarization of different guidelines for the sake of brevity.
RELATED:
Model Risk Management: Reduce your Model Risk through Coding Best Practices
Reducing Model Risk Through Modular Programming
Model Risk Management Through Archiving