Naming arguments and variables: Index and Number

It’s very common to have integers that are used to count objects. It’s also very common to have integers that are offsets into arrays (or similar structures).

Humans tend to count from 1 to n. In almost all cases when software uses offsets it makes sense to design the offset to run from 0 to n-1. Sometimes it is obvious which applies to a variable or function parameter. Sometimes this starts off being obvious but with the passage of time and the increase in the code complexity it becomes less obvious (even to the original code author). I know because I’ve been there.

There are also cases where it may not be so obvious from the start. Suppose you have a function which is passed the user response to the question “which one in this list of items do you want?”. Does the function return “1” if the user want’s the first one in the list or does it return zero?

I strongly encourage the use of the words “Index” in variable names which are expecting 0 to n-1 values and “Number” in variable names which are expecting 1 to n variables.

Thus you might declare the above function as

int GetUserSelectedNumber(void);

if the function returns 1 if the user selects the first item, or

int GetUserSelectedIndex(void);

if the function returns 0 if the user selects the first item.

Similarly if you have three things to control stored in an array, you might write:

const int NumberOfWidgets = 3;
TWidget Widgets[NumberOfWidgets];

and you could have a function somewhere that is declared as

void DoSomethingWithWidget(int WidgetIndex);

This is then immediately clear to everyone that the integer passed must run from 0 to n-1 (ie 0 to 3).

It’s a simple naming convention but it can save you hours when supporting your older (ongoing) code..

Advertisements

Modernise (Modernize [sic]) your VCL Applications for Windows 10

Embarcadero currently have an excellent series of webinars running which discuss various ways that the VCL framework supports Windows 10 features. Actually a lot of the content also applies to FireMonkey applications.

For more information go to this summary page

Android 64 bit compilation requirements – the future is secured !

Embarcadero have updated their road map to include Android 64 bit support for their C++ users. It is listed under “version 10.4.x – mid 2020”.

My last posting (22nd July 2019) suggested a short term work around for current C++ Android developers.

There has also been a 12 month extension granted by Android for Embarcadero C++ developers who have already got applications on the Google play store (this does not apply to new applications). Details are given here

Additional information is available here

This is good news for existing developers.

But the really good news is the appearance of the C++ for Android 64 bit in the road map. Embarcadero always restate that the road map is not binding but the reappearance of this product goal is an indication that they have realised this is an essential part of the C++ tool chain and it’s availability is vital to the survival of Embarcadero C++.

Go to the roadmap (as updated August 2019) by clicking here

Android 64 bit compilation requirements – a possible way around the limitation

As in my posting of Posted on 29th May 2019 it seems that Embarcadero have dropped the ability to compile for 64bit Android from the road map completely.

 This seems disastrous for all C++ Android / Firemonkey developers.

 One of the big names in Embarcadero C++ programming is Remy Lebeau.

He has offered a work around for C++ Android / Firemonkey developers at the following link.

How to get Android 32 bit apps onto google play store

It’s worth pointing out that this is only a short term solution and every C++ Android / Firemonkey developer should still be doing their best to pressurise Embarcadero to reconsider their decision.

 

FMX for Linux

Embarcadero have announced that those on subscription upgrade with Architect or higher license for Delphi or RAD studio can now install the FMX for Linux package.

 This promises Delphi users the ability to use the Firemonkey framework to write Linux GUI applications and as such is a major new development.

 Again it shows the advantage that Embarcadero have when developing products based on their propriety form of pascal (Delphi = Object Pascal). They don’t have to jump through many hoops to get the compiler targeting different operating systems.

 Even though RAD studio uses versions of open source (clang) C++ compilers (thus theoretically requiring no “original” development) Embarcadero seem reluctant to develop and sell C++ equivalents to their cutting edge Delphi offerings.

 As well as the lack of FMX for Linux using C++ there is also the recent lack of commitment to provide 64 bit C++ support for Android and iOS.

 If you are looking at Windows only applications then Embarcadero C++ (VCL or Firemonkey) is still a sound choice. But, in this day and age, how can you be sure that your application will remain in the “Windows only” category?

 For more information on FMX for Linux search on line for the webinar of 9th July 2019 “Introduction to FmxLinux – Delphi’s FireMonkey for Linux Solution” presented by Jim McKeeth.

Embarcadero Latest Road Map (May 2019)

 The latest road map for Embarcadero RAD Studio, C++ Builder and Delphi is now available at the link below.

 Multi-device Delphi users will be impressed with soon-to-be-with-us options and multi-device C++ users may be less impressed with the failure of the C++ side of multi-device development failing to keep up…..

 It’s an interesting read, here’s the link.

Embarcadero Road Map (May 2019)

 

C++ / Delphi with SurveyMonkey and Twilio

Embarcadero RAD Studio (C++ and/or Delphi) provides a convenient set of tools for interfacing to many third party web based APIs. These tools are known as “Enterprise Connectors”.

 In an effort to publicise these useful technologies Embarcadero are running a series of webinars on some of the more common ones

In May 2019 its the turn of the (disparate) pair: SurveyMonkey and Twilio

Click here for more information

Linux GUI using FireMonkey ?

The FireMonkey framework (commonly abbreviated to FMX) allows cross platform development for Windows, MacOS, iOS and Android from the same code base (either Delphi or C++).

A very common question is “when is FireMonkey for Linux coming?”. Embarcadero are regularly asked this and their reply is always along the lines of “we are keeping an eye on it but at present the market place doesn’t make it worth while”.

Developing general purpose tools for Linux is challenging because there are so many different versions of Linux out there.

However one firm ARE promoting FireMonkey for Linux – using Delphi as the supported language.

Interested parties may like to take a look at FMX for Linux

Stick with one Editor

To many this may be obvious. But it’s amazing how many people use the editor that comes with each of their IDEs with the confusion that arises as a consequence of each editor supporting different “advanced” features and/or short cut keys etc.

The Embarcadero IDE editor is a good one. Having got to learn it “inside out” I now use it for all major program writing. For example when working with Freescale microcontroller C code I use the Embarcadero editor for all code creation and only use the Freescale “Codewarrior” IDE editor for quick fixes whilst in the debugger.

Can you do better than returning a bool?

It’s very common to write functions that do something or check something and then return “ok” or “failed”.

When writing such functions one’s instinct is often to return a bool value. Let’s think of some hardware that monitors a digital input coming from a switch which is active when a valve is open.

We might declare the function as follows:

bool ValveLimitSwitchIsActive(void);

This is a sensible choice, the digital input can only be either active or inactive (any other condition must be a hardware failure) and our function matches this physical reality.

But what about if we want to check if the valve is open? We could declare a function as follows:

bool ValveIsOpen(void);

Great! we can now start to write code that works with the valve, using this function as required. All looks good? Perhaps not. Perhaps we have an operation on our plant which demands that the valve is definitely energised (could be safety critical) as well as being fully open. Perhaps we also want to monitor how long it takes for the valve to actually open. We could generate more functions:

bool ValveIsFullyOpenAndEnergised(void);
bool ValveIsEnergised(void);

but it all gets a bit messy….

How about

enum class TValveState {FullyClosed, Closing, Opening, FullyOpen};
// Opening == energised but not yet reached fully open limit switch

TValveState GetValveState(void);

This is good because all the valve checking is in one place. If the design of the valve interface changes we only have to modify this one function.

This still has good clear legibility at when the function is called; no one can be confused by:

if (GetValveState(void) == FullyClosed) { // do something here }

Because of this form of calling, the same technique is also very useful when dealing with functions that are harder to name in such a way that a bool return value makes sense. Consider a database update. We could have a function

bool UpdateDatabase(…); // returns true if update was successful

We call this using:

if (UpdateDatabase(…)) { // do something here – task }

This works, but if you come back to this code do you know if the task is executed if the update was successful, or if it was unsuccessful? The only way to be sure is to back to the body of the function UpdateDatabase – very bad from a programming maintenance perspective.

A simple improvement would be to write

bool UpdateDatabaseWasSuccessful(…)

but now you have a function name that suggests a status check on the database, it rather hides the fact that an action is actually carried out.

Much better is to use:

enum class TDatabaseUpdateResult {UpdatedOk, FailedToUpdate};

TDatabaseUpdateResult UpdateDatabase(…);

Now the call is fairly concise and very clear:

if (UpdateDatabase(…) == UpdatedOk) { // do something here – task }

Again, if we later decide to return more error information (perhaps different reasons why the update failed) we can simply add extra enum names.

We could even change the enum to a full blown class and return this, if we needed to.

It’s a good technique: use it!