While the previous two TechTips focused on the prefixes for different types of variables, this one is about the name itself. Here I explain why using simple names is of paramount importance to writing better code.

Choosing appropriate names for variables is as critical as correctly using the prefixes. Check out the previous two TechTips for a quick refresh on prefixes. For instance, W_DF is not very informative, but W_DeliveryFee or W_Delivery_Fee is. Choosing appropriate, meaningful names for variables makes your code more efficient in the sense that you’ll waste less time understanding and maintaining it later.

Other than the words themselves, you need to use some sort of separation between them to increase readability. “Modern” languages typically use something called “camel case.” The idea behind this funny name is that you capitalize the first letter of every word contained in the variable name, like W_DeliveryFee, thus creating a camel-like “hump” in the middle of the word’s “back.”

Another option is using the underscore character (_) to separate the words. This can create longer variable names, but it simplifies complicated names such as P_usdtoeur, which becomes P_USD_to_Eur. I usually use the underscore to separate the words, but as I said, this can lead to very long variable names. When the name gets too long, I switch to camel case.

Speaking of long names, did you know that the maximum length allowed by RPG for a variable is 4,096 characters? While it doesn’t make any sense whatsoever to even consider using such a long name, always keep in mind that you need to find the right balance between readability and maintainability: W_I_use_this_variable_to_store_the_value_converted_to_integer is way too long, while W_Converted_to_Int is equally informative but much more maintainable. However, this raises a question: You probably noticed that I abbreviated “integer” to “int”; should you abbreviate words in variable names?

The answer is “sometimes.” When the abbreviation is a common one, such as “Qty” for “Quantity” or “Amt” for “Amount,” you should, in my opinion, abbreviate it. Don’t abbreviate other words, though, or you’ll jeopardize your recently earned readability. For example, consider a variable that will hold a consistency check. It’s okay to abbreviate “check” as “chk” because that’s a fairly well-known abbreviation. However, don’t even consider abbreviating “consistency,” or you’ll risk confusing it with some other word starting with “C” later, when you (or another programmer) reads the code in a couple of months. So, a work variable related to a consistency check could be named W_Consistency_Chk, but not W_Cnstcy_Chk.

Naming Procedures and Functions

I’ve already mentioned the golden rule of function naming a couple of times in previous TechTips of this series, but it’s worth mentioning again: Function names should always start with a verb (which can be abbreviated or not, like a variable name) followed by the object over which the action (or the verb) is going to be performed. They should also be descriptive enough for a programmer to understand what the function does, in broad terms, without having to look at the function’s code. For instance, Retrieve_Item_Qty is the name of a function that retrieves the quantity of a given item; Itmqty, or anything similar, is just rubbish!

If your functions are built in such a way that they perform only one task, choosing an adequate name shouldn’t be a problem. In fact, if you look at any given function and find it hard to name, consider reviewing the function and splitting it into several smaller functions. If your function performs several tasks, then it shouldn’t be just one function. A good example of this is the Rtv_DayOfWeek function from earlier in the series, which can be split into two. In case you don’t remember, the original function performed two tasks; it calculated the day of the week, producing a numeric value that corresponded to each day (1 for Monday, 2 for Tuesday, and so on), and then it translated that numeric value into a human-readable value (Monday, Tuesday, etc.). So you can assign each of the tasks to a new function and name it appropriately: Clc_DayOfWeek and Rtv_DayOfWeek, respectively.

Naturally, there are always exceptions to this rule. Functions also encapsulate complex functionality, providing the programmer with a “black box” or API that he or she can use without caring how the function does what it does, and allowing the programmer to focus on the result that it makes available instead. This is the type of situation in which documentation helps a lot.

Some gurus advocate that you should prefix the function name (the verb+subject I mentioned earlier) with the name of the module. For instance, if the Clc_DayOfWeek and Rtv_DayOfWeek functions were included in a generic module named Dates, their names would be Dates_Clc_DayOfWeek and Dates_Rtv_DayOfWeek, respectively. While I don’t disagree with this naming convention, it has advantages and disadvantages. A big, yet manageable disadvantage is that the procedure names get longer, which can lead to some annoying misspellings. The main advantage is eliminating the risk of duplicated procedure names in two (or more) different service programs, which could cause a compilation error further down the road if you try to compile a program that uses both of those service programs.

The next TechTip will continue to discuss naming conventions, focusing on physical and logical file names. Until then, feel free to share your knowledge and experience with the rest of the readers in the comments section below. It’s always nice to hear from you!

Rafael Victória-Pereira has more than 20 years of IBM i experience as a programmer, analyst, and manager. Over that period, he has been an active voice in the IBM i community, encouraging and helping programmers transition to ILE and free-format RPG. Rafael has written more than 100 technical articles about topics ranging from interfaces (the topic for his first book, Flexible Input, Dazzling Output with IBM i) to modern RPG and SQL in his popular RPG Academy and SQL 101 series on mcpressonline.com and in his books Evolve Your RPG Coding and SQL for IBM i: A Database Modernization Guide. Rafael writes in an easy-to-read, practical style that is highly popular with his audience of IBM technology professionals.

Rafael is the Deputy IT Director - Infrastructures and Services at the Luis Simões Group in Portugal. His areas of expertise include programming in the IBM i native languages (RPG, CL, and DB2 SQL) and in "modern" programming languages, such as Java, C#, and Python, as well as project management and consultancy.

---

MC Press books written by Rafael Victória-Pereira available now on the MC Press Bookstore.

		Evolve Your RPG Coding: Move from OPM to ILE...and Beyond Transition to modern RPG programming with this step-by-step guide through ILE and free-format RPG, SQL, and modernization techniques. List Price $79.95 Now On Sale
		Flexible Input, Dazzling Output with IBM i Uncover easier, more flexible ways to get data into your system, plus some methods for exporting and presenting the vital business data it contains. List Price $79.95 Now On Sale
		SQL for IBM i: A Database Modernization Guide Learn how to use SQL’s capabilities to modernize and enhance your IBM i database. List Price $79.95 Now On Sale