Click here to close now.

Welcome!

Microsoft Cloud Authors: Liz McMillan, Elizabeth White, Pat Romanski, Jaynesh Shah, Carmen Gonzalez

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
17th Cloud Expo, taking place Nov 3-5, 2015, at the Santa Clara Convention Center in Santa Clara, CA, will feature technical sessions from a rock star conference faculty and the leading industry players in the world. Cloud computing is now being embraced by a majority of enterprises of all sizes. Yesterday's debate about public vs. private has transformed into the reality of hybrid cloud: a recent survey shows that 74% of enterprises have a hybrid cloud strategy. Meanwhile, 94% of enterprises are using some form of XaaS – software, platform, and infrastructure as a service.
The recent trends like cloud computing, social, mobile and Internet of Things are forcing enterprises to modernize in order to compete in the competitive globalized markets. However, enterprises are approaching newer technologies with a more silo-ed way, gaining only sub optimal benefits. The Modern Enterprise model is presented as a newer way to think of enterprise IT, which takes a more holistic approach to embracing modern technologies.
The true value of the Internet of Things (IoT) lies not just in the data, but through the services that protect the data, perform the analysis and present findings in a usable way. With many IoT elements rooted in traditional IT components, Big Data and IoT isn’t just a play for enterprise. In fact, the IoT presents SMBs with the prospect of launching entirely new activities and exploring innovative areas. CompTIA research identifies several areas where IoT is expected to have the greatest impact.
There's no doubt that the Internet of Things is driving the next wave of innovation. Google has spent billions over the past few months vacuuming up companies that specialize in smart appliances and machine learning. Already, Philips light bulbs, Audi automobiles, and Samsung washers and dryers can communicate with and be controlled from mobile devices. To take advantage of the opportunities the Internet of Things brings to your business, you'll want to start preparing now.
P2P RTC will impact the landscape of communications, shifting from traditional telephony style communications models to OTT (Over-The-Top) cloud assisted & PaaS (Platform as a Service) communication services. The P2P shift will impact many areas of our lives, from mobile communication, human interactive web services, RTC and telephony infrastructure, user federation, security and privacy implications, business costs, and scalability. In his session at @ThingsExpo, Robin Raymond, Chief Architect at Hookflash, will walk through the shifting landscape of traditional telephone and voice services ...
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 Internet of @ThingsExpo, James Kirkland, Chief Architect for the Internet of Things and Intelligent Systems at Red Hat, described how to revolutioniz...
The world is at a tipping point where the technology, the device and global adoption are converging to such a point that we will see an explosion of a world where smartphone devices not only allow us to talk to each other, but allow for communication between everything – serving as a central hub from which we control our world – MediaTek is at the heart of both driving this and allowing the markets to drive this reality forward themselves. The next wave of consumer gadgets is here – smart, connected, and small. If your ambitions are big, so are ours. In his session at @ThingsExpo, Jack Hu, D...
The security devil is always in the details of the attack: the ones you've endured, the ones you prepare yourself to fend off, and the ones that, you fear, will catch you completely unaware and defenseless. The Internet of Things (IoT) is nothing if not an endless proliferation of details. It's the vision of a world in which continuous Internet connectivity and addressability is embedded into a growing range of human artifacts, into the natural world, and even into our smartphones, appliances, and physical persons. In the IoT vision, every new "thing" - sensor, actuator, data source, data con...
All major researchers estimate there will be tens of billions devices - computers, smartphones, tablets, and sensors - connected to the Internet by 2020. This number will continue to grow at a rapid pace for the next several decades. With major technology companies and startups seriously embracing IoT strategies, now is the perfect time to attend @ThingsExpo, June 9-11, 2015, at the Javits Center in New York City. Learn what is going on, contribute to the discussions, and ensure that your enterprise is as "IoT-Ready" as it can be
SYS-CON Events announced today that MetraTech, now part of Ericsson, has been named “Silver Sponsor” of SYS-CON's 16th International Cloud Expo®, which will take place on June 9–11, 2015, at the Javits Center in New York, NY. Ericsson is the driving force behind the Networked Society- a world leader in communications infrastructure, software and services. Some 40% of the world’s mobile traffic runs through networks Ericsson has supplied, serving more than 2.5 billion subscribers.
The 4th International Internet of @ThingsExpo, co-located with the 17th International Cloud Expo - to be held November 3-5, 2015, at the Santa Clara Convention Center in Santa Clara, CA - announces that its Call for Papers is open. The Internet of Things (IoT) is the biggest idea since the creation of the Worldwide Web more than 20 years ago.
SYS-CON Events announced today that O'Reilly Media has been named “Media Sponsor” of 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. O'Reilly Media spreads the knowledge of innovators through its books, online services, magazines, and conferences. Since 1978, O'Reilly Media has been a chronicler and catalyst of cutting-edge development, homing in on the technology trends that really matter and spurring their adoption by amplifying "faint signals" from the alpha geeks who are creating the future. An active participa...
We’re entering a new era of computing technology that many are calling the Internet of Things (IoT). Machine to machine, machine to infrastructure, machine to environment, the Internet of Everything, the Internet of Intelligent Things, intelligent systems – call it what you want, but it’s happening, and its potential is huge. IoT is comprised of smart machines interacting and communicating with other machines, objects, environments and infrastructures. As a result, huge volumes of data are being generated, and that data is being processed into useful actions that can “command and control” thi...
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.
There's Big Data, then there's really Big Data from the Internet of Things. IoT is evolving to include many data possibilities like new types of event, log and network data. The volumes are enormous, generating tens of billions of logs per day, which raise data challenges. Early IoT deployments are relying heavily on both the cloud and managed service providers to navigate these challenges. In her session at Big Data Expo®, Hannah Smalltree, Director at Treasure Data, discussed how IoT, Big Data and deployments are processing massive data volumes from wearables, utilities and other machines...
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 will peel 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 fil...
With major technology companies and startups seriously embracing IoT strategies, now is the perfect time to attend @ThingsExpo in Silicon Valley. Learn what is going on, contribute to the discussions, and ensure that your enterprise is as "IoT-Ready" as it can be! Internet of @ThingsExpo, taking place Nov 3-5, 2015, at the Santa Clara Convention Center in Santa Clara, CA, is co-located with 17th Cloud Expo and will feature technical sessions from a rock star conference faculty and the leading industry players in the world. The Internet of Things (IoT) is the most profound change in personal an...
The worldwide cellular network will be the backbone of the future IoT, and the telecom industry is clamoring to get on board as more than just a data pipe. In his session at @ThingsExpo, Evan McGee, CTO of Ring Plus, Inc., discussed what service operators can offer that would benefit IoT entrepreneurs, inventors, and consumers. Evan McGee is the CTO of RingPlus, a leading innovative U.S. MVNO and wireless enabler. His focus is on combining web technologies with traditional telecom to create a new breed of unified communication that is easily accessible to the general consumer. With over a de...
Disruptive macro trends in technology are impacting and dramatically changing the "art of the possible" relative to supply chain management practices through the innovative use of IoT, cloud, machine learning and Big Data to enable connected ecosystems of engagement. Enterprise informatics can now move beyond point solutions that merely monitor the past and implement integrated enterprise fabrics that enable end-to-end supply chain visibility to improve customer service delivery and optimize supplier management. Learn about enterprise architecture strategies for designing connected systems tha...
From telemedicine to smart cars, digital homes and industrial monitoring, the explosive growth of IoT has created exciting new business opportunities for real time calls and messaging. In his session at @ThingsExpo, Ivelin Ivanov, CEO and Co-Founder of Telestax, shared some of the new revenue sources that IoT created for Restcomm – the open source telephony platform from Telestax. Ivelin Ivanov is a technology entrepreneur who founded Mobicents, an Open Source VoIP Platform, to help create, deploy, and manage applications integrating voice, video and data. He is the co-founder of TeleStax, a...