Game of Code

Or “write code like you immediately forget what you wrote” so it’s not a guessing game to figure out why you wrote what you wrote way back when.

What do I mean by that ?

Write code CLEARLY. Use constants liberally and give them good meaningful names.

So instead of writing a line like

If asc(key) = 16 or asc(key) = 204 then

where 16 and 204 are not obvious to everyone maybe write this as

Const ctrlP = 16
Const F5 = 204

if asc(key) = ctrlP  or asc(key) = F5 then

And then even when you go back and look at this code in 6 months even you won’t have to guess what 16 and 204 mean.

What scope should this be ?

This question isnt asked that often. But I think it should be.

When you create classes, modules, layouts or anything else in Xojo you should make everything as private as it needs to be. And no more. And as public as it needs to be. And no more.

But exactly what does that mean ?

I would say that you should normally start with most things in classes being protected. This means that any subclasses can access the items in the class. But code outside the class cant access it. This gives you a decent way to sort out what API you want the class to expose and grow that exposed API over time rather than just making everything publicly accessible all the time.

Code and controls on layouts I would treat similarly and make them all private since you only have private or public to chose from.

For modules public is also a good default for many of the same reasons. But in the case of a method or property in a module that is public it CAN be accessed by code outside the module it just has to be fully qualified so there’s no ambiguity when you are using such a thing.

In my time as a product engineer at Xojo I fixed a lot of bugs and many times the issue turned out to be code outside some class, module or layout that was accessing and changing or calling a method that wasnt protected or private and it was doing so at an inopportune time and so it appeared to be a bug in the Xojo framework.

Properly encapsulate your code and expose only as much as needs to be exposed whether thats by methods, events or properties. And by doing this you will prevent all kinds of weird coding bugs in your own projects.

More good habits

On the forum there was a suggestion that a person should use a container control that had a few controls embedded in it at design time. And then when using that container control that they should skip providing an API that the container presented and just reach inside the container and manipulate the controls it contain directly.

Personally I would recommend against this.

I’d start by saying when you create a container control ALL the controls in it should be private by default to prevent this. And that if you want to expose functionality of the controls on the container you do so by defining methods and events on the container that any code OUTSIDE the container can call or react to just as if the container control was any other single control and not a composite one like it is.

Why would I make such a recommendation ?

  1. good habits
  2. encapsulation
  3. reusability
  4. long term flexibility and maintainability

The first point is just that this is a good habit to get into. And the reason its a good habit is because of points 2, 3 and 4. Properly encapsulating and hiding the details from other bits of your code is a good thing. Code outside the container doesnt need to know HOW the container does what it does. Just that it does what is expected when you call its methods, change its properties and react to the events it exposes. Thats it. It should be a black box like the built in Xojo listbox, pushbutton, or any other built in control is. You dont need to know how those do what they do, just that they do what you expect when you call the methods, set the properties and react to their events.

And the bonus to doing this is that it makes the likelihood you, or others, can reuse your control in more places in your project or in other projects much higher because the control is self contained.

Long term it also lets you do things like completely swap out the implementation of the container for some other means and as long as you dont need to change the API nothing outside the container control even needs to be aware this has happened. This makes your own code easier to maintain since you no longer have to look through all the code outside of the container to know if you also need to alter it because something in the container changed.

These are all good things regardless of whether this code is for your own use, more general distribution or possibly for sale or to give away.

I’d encourage everyone to keep these things in mind when ever they write their own custom controls.

How do you raiseevent ?

When you create a custom control from a canvas, container control or some other base class its not unusual to use raise event to create new events like “BeforeButtonPressed”, “AfterButtonPressed” or to just make it so you;r control can implement normal events like Open, Close, etc and pass then along.

You’ll see code using raiseevent to cause these events to be raised on any instances.

But, you can use raiseevent for much more than this and use it in places you might not expect.

For instance, you might want an event to return a boolean as well as some parameter byref much like the SelectColor method does.

Dim c As Color

If SelectColor(c) Then
  // use the color selected
Else
  // c is still "default"
End If

This isnt so bad and it easy to imagine writing the SelectColor method to do exactly this. But what if SelectColor is an event in a custom control you’re writing ? You might be tempted to write

Dim c As Color

Dim b As Boolean = SelectColor(c)

If b Then
  // use the color selected
Else
  // c is still "default"
End If

But in a way this hides the fact that SelectColor IS an event your code is calling for an instance to implement. Believe it or not you CAN write

Dim c As Color

Dim b As Boolean = RaiseEvent SelectColor(c)

If b Then
  // use the color selected
Else
  // c is still "default"
End If

And this then is more obvious that SelectColor IS an event that an instance might have implemented. But, since you can write that why not

Dim c As Color = &cffffff

If RaiseEvent SelectColor(c) Then
  // use the color selected
Else
  // c is still "default"
End If

And once again this works just as we expect. And it helps make your code clearer that you ARE calling an event that an instance may have implemented. And, code clarity is a good thing.

I think if you try you might be surprised at the spots where putting RaiseEvent works exactly as expected and helps improve code clarity.

Let the compiler help you

An interesting question posed by a relatively new user came up on the forums. It had to do with how the Array() function worked and how he could force it to return an array of variants to call his method.

His method was defined like

BuildMenu( base as menuitem, params() as variant)

And he would call it like

Result = BuildMenu (base, Array ("Run", False, "Edit", "Rename", "Delete") )

and this would build up a menu from the base item and append menu items to it. Those new menu items were configured by the array of variants

‘False’ means the previous menu item is disabled (‘True’ means it is enabled, but is optional and assumed)

Because the boolean elements are optional, it is possible to make a call using only string elements, such as:

Result = BuildMenu (base, Array (“Run”, “Edit”, “Rename”, “Delete”) )

But when I do this, I get the following compile error:

So he’s trying to figure out how to force Array to return variants ALL the time. Which is the wrong question to ask in many ways.

Using an array of variants means the compiler cannot help you out and tell you when you are trying to assign the wrong kind of value to another.

Normally if you did something like

dim foo as integer
foo = "123"

the compiler will warn you about this. But if you change this simple code to :

dim foo as variant
foo = "123

you will no longer get a compile error. And depending on how you use “foo” you may, or may not, get some kind of runtime error.

This is why some of the long time users of Xojo suggest avoiding variants unless you absolutely cannot do something any other way.

Variants make it possible to bypass and avoid type checking by the compiler. What this means is that by using a variant you are possibly only finding out about errors at runtime because the compiler cannot do its normal helpful type checking to make sure you catch errors early on.

So in this particular thread on the forums the right question isn’t “how to force the array() function to always return a variant array” but “how to design this particular API so variants are not required”. And that is certainly possible since Xojo supports variable argument lists, optional parameters and other features that retain strong type checking at compile time AND still allow for a good degree of flexibility in designing an API.

And I made a suggestion on that thread :

Result = BuildMenu (base, BuildItem( “Run”, false), BuildItem(“edit”), BuildItem(“Rename”), BuildItem(“Delete”))
with buildmenu defined as

Sub BuildMenu(base as menuitem, paramarray items as menuitem)
// just append the items passed to the base
for i as integer = 0 to items.ubound
base.append items(i)
next
end sub

and BuildItem as

Function BuildItem(name as string, enabled as boolean = false)
dim item as new menuitem(name)
item.enabled = enabled
return item
end function

Avoid variants where you can and design an API that permits the compiler to help you out at compile time. The earlier you catch possible bugs the easier, and less costly, they are to fix.

The compiler can help you IF you let it.

Picking a good name

Not for your children (although that is important too since kids can be incredibly harsh and will pick on kids with names that they think sound different or odd)

This is to do with naming methods, properties, and just about everything else in your Xojo projects.

A good name indicates a number of things to anyone who reads the code. Purpose is the most obvious.

If all you had was a lot of methods named “foo” or “untitled” your application would be incredibly hard to figure out and maintain for very long.

So having a method named

SplitPropertyValuesIntoDictionary(jsonSource as JSonItem) as Dictionary

Gives you a decent idea what this method will do just by reading the full description and the names of the parameters.

Events have similar naming issues. They should convey what is happening when they are raised. “Action” has never been a great name for the event that is raised by a pushbutton when it is clicked on. Its not entirely horrid but it could be better.

Pushed() 

might be better since that is what has occurred in a push button.

Some events happen DURING some other action. For instance when an expandable row in a listbox is clicked on you currently get a “ExpandRow” event – which might mislead you into thinking you have to write some code to actually DO the expansion like setting the rows expanded property to true as well as other code. Again the name isnt horrible but it could be better.

RowExpanding()

more closely reflects when the event is being raised; during the rows normal course of expanding. Again though this doesn’t convey much information about what is expected. Can you cancel the row from being expanded ? Without reading the documentation this name doesn’t tell you much.

AddRowsToRowExpanding()

might be even better as it tells you exactly what this event is for.

Now I know some will say “OMG thats so much typing” – yes – if you type every last thing out by hand. Learn to use Autocomplete and it will help you immensely and may even help you find other useful properties, methods etc that you may not know existed.

The better you pick names the more easily your code documents itself. I’m not advocating writing no comments in code but they should be about the general process being performed not the mechanics (unless the mechanics are really hairy)

see this excellent post about this subject