Click here to close now.

Welcome!

Microsoft Cloud Authors: Aleksei Gavrilenko, Elizabeth White, Liz McMillan, Pat Romanski, Jaynesh Shah

Related Topics: PowerBuilder, Microsoft Cloud

PowerBuilder: Article

Elegant Programming: The Art of Naming (Part 1)

Names should be self-explanatory

Give all entities mentioned in the code (DB tables, DB tables' fields, variables, classes, functions, etc.) meaningful, descriptive names that make the code easily understood. The names should be so self-explanatory that it eliminates the need for comments in most cases.

Use the words per and by as often as possible - they really simplify a developer's life. A variable's name li_cows_per_farm is better than li_total_cows, and a function name uf_retrieve_city_by_country tells us more than uf_retrieve_city, especially if it doesn't have parameters that supply the "by what" information.

Don't use abstract words like "actual" and "total' in variables names as they will madden you, forcing to spend extra time trying to understand what is "actual," what is "not actual" and which grouping level is "total" for. Is li_total_cows field total per barn? per farm? per village? per province? per country? per the Universe? If, for example, per farm, then how will you name the total per village? It's also "total"! So, don't write simply "total" - write total PER WHAT! Use only exact definitions that produce no (or minimum) questions, even if that results in longer variables names.

*** BAD code: ***

ldc_total_salary = ldc_actual_salary * ldc_total_hours

*** GOOD code: ***

ldc_salary_per_day = ldc_salary_per_hour * ldc_hours_per_day

Exact Meaning
Consistency

Don't produce different versions of a same entity name (like emp_id / employee_id, inv_num / invoice_num).

When you use values retrieved from database tables, try to name the corresponding variables exactly by the DB fields (of course, adding naming convention prefixes where needed). But you can use local variables' names more freely, especially when the coded logic is complicated while the tables fields are not informative enough (see the previous rule).

Long, Descriptive Names
The common, obvious practice is to give variables and functions short names. But, sometimes, there are situations when it makes sense to break that rule and use long, "real-English" names that will clearly describe what they are for.

For example, it can be done when a variable is in a rare use (like an instance var, which is referenced only a couple of times), but not a local var which is mentioned in the code many times. Anyway, don't be afraid to give long names any time you feel it will simplify working with the code. See the difference between:

is_main_filter = uf_get_main_filter()

and

is_filter_by_selected_row_in_summary_win = uf_get_filter_by_selected_row_in_summary_win()

As you can see, names of variables can tell the whole story. Even if it makes a line too long, there is no problem breaking it into two lines - it's better than looking at a variable and having no idea what is stored in it (or to search its declaration in hopes that a clarifying comment exists). But remember - names of that style should be an exception, not a rule.

Exact Action Timing
Names describing actions must express if the action should be done in the future or was done in the past.

Giving names to variables, don't force readers to guess an action timing. A good example of a bad variable name is lb_is_calculation. How must the condition "if lb_is_calculation then..." be understood? As you can see, there is no problem exists understanding what it means if the variable is named lb_is_calculation_done (lb_is_calculated) or in the imperative form - lb_do_calculation (or simply lb_calculate).

The common advice is to use words do..., ...to_do, perform..., execute..., ...to_apply, etc., for stuff that should take place in the future, and ...done, ...performed, ...executed, ...occurred, ...passed, ...applied, etc., for things that have taken place in the past.

Constants
Constants for [Meaningless] Application Codes

Don't hard code numbers if they are not apparent - use constants instead.

Okay, it's still possible to understand what "if li_inv_year > 2011..." or "if li_month = 4..." is but what do you want to say to a programmer who has written "if li_window_mode = 3..." or "if li_inv_status = 8..."?

Local and Instance Constants Management
Giving names to local and instance constants, divide the family prefix from the mnemonic description by two underscores.

Now let's discuss local and instance-scope constants. Their names must consist of two parts:

  • Group (or "family") - like "ORDER_STATUS" or "INVOICE_STATUS". A few constants of the same family can co-exist in the scope (for example, an order can have many statuses). In fact, it's a prefix before the main descriptive part.
  • Description (or mnemonic part) - like "OPEN" or "CLOSED". There can be many constants with the same description (for example, both - an order and an invoice - can have the status "OPEN").

Using two underscores (instead of one) to connect both parts will allow code readers to easily distinguish between them, especially when each part consists of a number of words. For example:

private:

constant string ORDER_STATUS__OPEN = "OPN"
constant string ORDER_STATUS__CLOSED = "CLS"
constant string ORDER_STATUS__CANCELED = "CNCL"

constant string INV_STATUS__OPEN = "OPN"
constant string INV_STATUS__CLOSED = "CLS"
constant string INV_STATUS__CANCELED = "CNCL"

Global Constants Management
Constants, used globally (in different parts of the application), must be declared in not-autoinstantiated NVOs - one NVO per each constants group (or "family") - and accessed via the automatically created global reference variable with the same name, without declaring additional variables and creating instances.

For example, you can have an NVO named n_color for color constants, n_order_status for order statuses constants, etc. It's a good idea to keep them all in one PBL so developers can easily check if the NVO for the group they need already exists or must be created. The constants are declared in the instance variables declaration section in a very straightforward way. Here is a possible set for n_order_status:

public:

constant string OPEN = "OPN"
constant string CLOSED = "CLS"
constant string CANCELED = "CNCL"

If you open any not-autoinstantiated class in the "View Source" mode, you can see that PowerBuilder automatically creates a global variable of that object's type with the same name as the class (PB doesn't know that we add "g" to global vars! :-D ). For example, if you create n_order_status class (not-autoinstantiated, remember?) and look at its source, you'll see the following line:

global n_order_status n_order_status

That's exactly the mentioned declaration of the global var. You don't need to declare a variable of the object each time you need to use a constant in your script - you already have a variable ready for use. That's how you mention a constant in the code:

n_order_status.OPEN

Looking pretty similar to enum of C# but, unfortunately, it's not an enumerated type; you cannot declare a function argument of type n_order_status and pass to that function one of the statuses (which is of type string) defined in the type - you can only pass a reference to n_order_status object, which doesn't solve the problem of passing type-safe arguments. You can make the argument of type string to pass a particular status, but this approach doesn't supply type safety - nothing prevents you from passing an invoice status or even the name of your cat...

Pay attention that PowerBuilder only declares a global variable; it doesn't create an object referenced by that variable. Practically it means that we can use only constants because they belong to a type (not an instance) definition (something similar to static data in C#). If you try to access an instance variable or a function of that global var, then you will get the "Null object reference" error. As opposed to C#, which will happen even if the function doesn't access instance data, so there is nothing like C#'s "static function" behavior in PowerBuilder.

For standalone constants (not belonging to any family) create one common NVO named, let's say, n_const.

More Stories By Michael Zuskin

Michael Zuskin is a certified software professional with sophisticated programming skills and experience in Enterprise Software Development.

Comments (0)

Share your thoughts on this story.

Add your comment
You must be signed in to add a comment. Sign-in | Register

In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.


@ThingsExpo Stories
The basic integration architecture, as defined by ESBs, hasn’t changed for more than a decade. Most cloud integration providers still rely on an ESB architecture and their proprietary connectors. As a result, enterprise integration projects suffer from constraints of availability and reliability of these connectors that are not re-usable across other integration vendors. However, the rapid adoption of APIs and almost ubiquitous availability of APIs amongst most SaaS and Cloud applications are rapidly redefining traditional integration approaches and their reliance on proprietary connectors. ...
The Internet of Things is not only adding billions of sensors and billions of terabytes to the Internet. It is also forcing a fundamental change in the way we envision Information Technology. For the first time, more data is being created by devices at the edge of the Internet rather than from centralized systems. What does this mean for today's IT professional? In this Power Panel at @ThingsExpo, moderated by Conference Chair Roger Strukhoff, panelists addressed this very serious issue of profound change in the industry.
Internet of Things is moving from being a hype to a reality. Experts estimate that internet connected cars will grow to 152 million, while over 100 million internet connected wireless light bulbs and lamps will be operational by 2020. These and many other intriguing statistics highlight the importance of Internet powered devices and how market penetration is going to multiply many times over in the next few years.
Today air travel is a minefield of delays, hassles and customer disappointment. Airlines struggle to revitalize the experience. GE and M2Mi will demonstrate practical examples of how IoT solutions are helping airlines bring back personalization, reduce trip time and improve reliability. In their session at @ThingsExpo, Shyam Varan Nath, Principal Architect with GE, and Dr. Sarah Cooper, M2Mi’s VP Business Development and Engineering, will explore the IoT cloud-based platform technologies driving this change including privacy controls, data transparency and integration of real time context wi...
Internet of Things (IoT) will be a hybrid ecosystem of diverse devices and sensors collaborating with operational and enterprise systems to create the next big application. In their session at @ThingsExpo, Bramh Gupta, founder and CEO of robomq.io, and Fred Yatzeck, principal architect leading product development at robomq.io, discussed how choosing the right middleware and integration strategy from the get-go will enable IoT solution developers to adapt and grow with the industry, while at the same time reduce Time to Market (TTM) by using plug and play capabilities offered by a robust IoT ...
"We have a tagline - "Power in the API Economy." What that means is everything that is built in applications and connected applications is done through APIs," explained Roberto Medrano, Executive Vice President at Akana, in this SYS-CON.tv interview at 16th Cloud Expo, held June 9-11, 2015, at the Javits Center in New York City.
Explosive growth in connected devices. Enormous amounts of data for collection and analysis. Critical use of data for split-second decision making and actionable information. All three are factors in making the Internet of Things a reality. Yet, any one factor would have an IT organization pondering its infrastructure strategy. How should your organization enhance its IT framework to enable an Internet of Things implementation? In his session at @ThingsExpo, James Kirkland, Red Hat's Chief Architect for the Internet of Things and Intelligent Systems, described how to revolutionize your archit...
WebRTC converts the entire network into a ubiquitous communications cloud thereby connecting anytime, anywhere through any point. In his session at WebRTC Summit,, Mark Castleman, EIR at Bell Labs and Head of Future X Labs, will discuss how the transformational nature of communications is achieved through the democratizing force of WebRTC. WebRTC is doing for voice what HTML did for web content.
It is one thing to build single industrial IoT applications, but what will it take to build the Smart Cities and truly society-changing applications of the future? The technology won’t be the problem, it will be the number of parties that need to work together and be aligned in their motivation to succeed. In his session at @ThingsExpo, Jason Mondanaro, Director, Product Management at Metanga, discussed how you can plan to cooperate, partner, and form lasting all-star teams to change the world and it starts with business models and monetization strategies.
To many people, IoT is a buzzword whose value is not understood. Many people think IoT is all about wearables and home automation. In his session at @ThingsExpo, Mike Kavis, Vice President & Principal Cloud Architect at Cloud Technology Partners, discussed some incredible game-changing use cases and how they are transforming industries like agriculture, manufacturing, health care, and smart cities. He will discuss cool technologies like smart dust, robotics, smart labels, and much more. Prepare to be blown away with a glimpse of the future.
SYS-CON Events announced today that BMC will exhibit at SYS-CON's 16th International Cloud Expo®, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY. BMC delivers software solutions that help IT transform digital enterprises for the ultimate competitive business advantage. BMC has worked with thousands of leading companies to create and deliver powerful IT management services. From mainframe to cloud to mobile, BMC pairs high-speed digital innovation with robust IT industrialization – allowing customers to provide amazing user experiences with optimized IT per...
There will be 150 billion connected devices by 2020. New digital businesses have already disrupted value chains across every industry. APIs are at the center of the digital business. You need to understand what assets you have that can be exposed digitally, what their digital value chain is, and how to create an effective business model around that value chain to compete in this economy. No enterprise can be complacent and not engage in the digital economy. Learn how to be the disruptor and not the disruptee.
The Internet of Things is not only adding billions of sensors and billions of terabytes to the Internet. It is also forcing a fundamental change in the way we envision Information Technology. For the first time, more data is being created by devices at the edge of the Internet rather than from centralized systems. What does this mean for today's IT professional? In this Power Panel at @ThingsExpo, moderated by Conference Chair Roger Strukhoff, panelists will addresses this very serious issue of profound change in the industry.
Business as usual for IT is evolving into a "Make or Buy" decision on a service-by-service conversation with input from the LOBs. How does your organization move forward with cloud? In his general session at 16th Cloud Expo, Paul Maravei, Regional Sales Manager, Hybrid Cloud and Managed Services at Cisco, discusses how Cisco and its partners offer a market-leading portfolio and ecosystem of cloud infrastructure and application services that allow you to uniquely and securely combine cloud business applications and services across multiple cloud delivery models.
In his General Session at 16th Cloud Expo, David Shacochis, host of The Hybrid IT Files podcast and Vice President at CenturyLink, investigated three key trends of the “gigabit economy" though the story of a Fortune 500 communications company in transformation. Narrating how multi-modal hybrid IT, service automation, and agile delivery all intersect, he will cover the role of storytelling and empathy in achieving strategic alignment between the enterprise and its information technology.
Buzzword alert: Microservices and IoT at a DevOps conference? What could possibly go wrong? In this Power Panel at DevOps Summit, moderated by Jason Bloomberg, the leading expert on architecting agility for the enterprise and president of Intellyx, panelists peeled away the buzz and discuss the important architectural principles behind implementing IoT solutions for the enterprise. As remote IoT devices and sensors become increasingly intelligent, they become part of our distributed cloud environment, and we must architect and code accordingly. At the very least, you'll have no problem fillin...
Growth hacking is common for startups to make unheard-of progress in building their business. Career Hacks can help Geek Girls and those who support them (yes, that's you too, Dad!) to excel in this typically male-dominated world. Get ready to learn the facts: Is there a bias against women in the tech / developer communities? Why are women 50% of the workforce, but hold only 24% of the STEM or IT positions? Some beginnings of what to do about it! In her Opening Keynote at 16th Cloud Expo, Sandy Carter, IBM General Manager Cloud Ecosystem and Developers, and a Social Business Evangelist, d...
Converging digital disruptions is creating a major sea change - Cisco calls this the Internet of Everything (IoE). IoE is the network connection of People, Process, Data and Things, fueled by Cloud, Mobile, Social, Analytics and Security, and it represents a $19Trillion value-at-stake over the next 10 years. In her keynote at @ThingsExpo, Manjula Talreja, VP of Cisco Consulting Services, discussed IoE and the enormous opportunities it provides to public and private firms alike. She will share what businesses must do to thrive in the IoE economy, citing examples from several industry sectors.
In his keynote at 16th Cloud Expo, Rodney Rogers, CEO of Virtustream, discussed the evolution of the company from inception to its recent acquisition by EMC – including personal insights, lessons learned (and some WTF moments) along the way. Learn how Virtustream’s unique approach of combining the economics and elasticity of the consumer cloud model with proper performance, application automation and security into a platform became a breakout success with enterprise customers and a natural fit for the EMC Federation.
SYS-CON Events announced today that the "Second Containers & Microservices Conference" will take place November 3-5, 2015, at the Santa Clara Convention Center, Santa Clara, CA, and the “Third Containers & Microservices Conference” will take place June 7-9, 2016, at Javits Center in New York City. Containers and microservices have become topics of intense interest throughout the cloud developer and enterprise IT communities.