Most shops have some sort of coding standard. Are yours creating consistency or holding you back?

In my day job, I spend a lot of time looking at other people's code. Helping customers and prospects plan for their modernization efforts is not only what I do, it's what I love. Whether I'm just doing analysis or building a proof of concept for a customer, I get to interact with different shops' developers and applications. This gives me some insight into the industry at large and often provides me with topics on which to write.

This month, I want to talk about coding standards. The mention of the topic makes some managers and developers all warm and fuzzy and others cringe. I fall somewhere in the middle. I understand both sides of the argument, and I think a little bit of dialogue can go a long way. Let's break the discussion into categories.

The Good

Standards have a place. They can add consistency to your code and greatly reduce the time needed to analyze code or research bugs. Naming conventions and application structure should adhere to a standard.

Naming conventions are often the easiest standard to implement. Whether you're talking about program names, module names, subprocedure names, variable names, or any other type element, the names should follow some sort of pattern. The pattern will not be the same for each of these element types, but each should have a defined pattern to follow. What pattern you use is highly dependent on the allowed length of the name and what information needs to be conveyed by the name.

Programs, files, and source members are restricted to 10 characters by the system, which makes naming more difficult. The most common patterns I see for these system objects are:

• XXYZZZZZZZ—XX represents a functional area, such as AR, AP, or OE. Y represents the programming language used (R, C, D, etc.). The remaining characters are an abbreviated description of what the object does.
• XXXXXXXXXY—The Xs represent a description of the object's function, and the last character or two is for the programming language or object type.

Subprocedures and variables in RPG have no practical limit to the length of their names. This allows for much greater flexibility. A subprocedure formatted XXXXX_YYYYYYYYY, for example, can be used to represent the service program in the "X" section and the procedures function in the "Y" section. This can be very useful to avoid name collisions when working with multiple applications and service programs. This also lets a developer immediately know where the procedure is located should more investigation be needed.

Standards on application structure also encourage uniformity in an application. If you are using RPG ILE, and you should be, it is important to be organized when building service programs and their associated sources. How many procedures are too many for a service program? How are procedures divided into service programs? I like to build my service programs to represent functional blocks or objects. So I may have a PURCHORDER service program and all procedures related to purchase orders would be contained within.

The Bad

Your standards should never limit your developers' creativity. While some may think a developer's job is to write code, they are really there to solve problems. Standards should help developers solve problems, not hinder them. Never create standards to make code palatable by the lowest level of knowledge in your shop. Just as a standard can assist in understanding for all, a properly envisioned standard can also drive developers to learn new techniques and sharpen their skills.

If your shop standard forbids the use of ILE or new built-in functions (BIFs) and opcodes, you're doing it wrong. How can you modernize your applications or implement exciting new application functionality if you can't make use of all of the features available to your developers? I hear developers tell me these things all the time. Some shops don't allow ILE for fear that some developers may not understand it. How will they ever learn to understand it if they don't use it? Some shops outlaw ILE because a developer used it once 10 years ago and it was "flakey." As with anything, you can't expect to get everything right the first time. You learn from mistakes and adapt.

The Ugly

Believe it or not, I hear about shops regularly that allow only RPG III to be used. Others allow RPG IV but still require six-character field names, fixed-format code, program-described files, and other outdated techniques. I simply could not work in such a place. How does this happen? I have seen a few different scenarios.

In some cases, there are a handful of very senior level developers who do not want to learn new things. These developers are often nearing retirement and have spent many years with the company. Less-technical managers often rely on them for direction on programming matters and dictate what they feel is best. This can be a tough nut to crack, but luckily, the situation often corrects itself as these more stubborn developers retire.

In other cases, you may have a manager who was once a developer and likes to micromanage. This type of manager wants to read code and set standards but doesn't have the time or desire to study new language features. I sometimes laugh to myself when someone says, "We don't use that new stuff." That new stuff has often been in the language or operating system for decades. The best advice I can offer if you're in this boat is to make a case for using new techniques. Don't just ask if you can do it. Take the time to put together a document or presentation on why you wish to do it, what benefits there are for developers, and what benefits there are to the company. Often, with a well-prepared argument, you can win over other developers and even your manager.

Doing It Right

So I have discussed the pros and cons of standards, but what do I recommend? I'm glad you asked! You may be surprised that I never recommend specific standards for shops to implement. I often offer insight based on my experiences, but in the end, standards are better received when they're created by those who must live by them. What I can offer are some suggestions and guidelines on how to make them better.

Standards should be an evolving set of guidelines. The problem with standards in most shops is that they're created, written in stone, and never revisited. At a minimum, you should be revamping your standards after every OS or compiler upgrade. Each upgrade will bring new features to the table, and your standards should take them into account. I recommend standards be reevaluated every other year unless you have an upgrade within that time period. Even without enhancement to the system or language used, your staff's skills should be improving and your standards should be updated to reflect this.

An even better approach could be to have a monthly or semimonthly lunch discussion on pain points with your standards or just have developers share new techniques they have learned with the staff. Have the company order in lunch or have the staff bring their own lunches. Lunch discussions are a great way to work on broader goals, such as standards, without cutting into project time. Will you revise your standards in one lunch meeting? Of course not! But over time, you can make progress. And when you "finish" your standards, continue to meet. Creating standards should be an iterative process.

In the end, it's up to you and your shop to decide on standards, so make your voice heard and encourage collaboration on the topic. If you don't have standards, you should create some. They can be a very great thing. If you do have standards, when was the last time you updated them? Software development is an ever-changing art form. Don't let your company's coding standards hold your application back. Now, let's get to it.

Brian May, an IBM Power Systems Champion and Solutions Architect for Profound Logic Software, devotes the majority of his time to assisting customers with their modernization efforts. He frequently writes and speaks on topics related to RPG, JavaScript, and IBM i Modernization. Brian recently contributed his time and expertise to the new IBM i Modernization Redbook.

 

Also Read

Advanced/Free - Function Calls and Return Values

PRACTICAL ILE - ILE Service Programs

Data-Manipulation Operations Using Free Format, Part Two