Reading other people’s code

by Michael McCreary on April 11, 2014 11 comments

Things are pretty hectic here in the LiveCode office at the moment. Not only are there 3 (yes three) separate versions of LiveCode out there for testing (6.6, 6.7 and 7.0), each with there own set of new features, there are also several projects being worked on that are still in their infancy. These new projects will form the basis of future LiveCode releases. It’s tricky to decide when to end development on one project and begin working on another. That’s often why as developers we find ourselves working on several things at any one time.

As we’re preparing to draw a line under the 6.5/6.6 cycle (with the release of LiveCode 6.6.2 – naturally we’ll still be fixing any bugs that crop up in these versions), I find myself doing a lot of debugging and sifting through old sections of code. And this got me thinking about coding style and specifically how we comment code. Each developer appears to have their own particular way of doing things. I’m trying to decide which I prefer. Here are a few that I have come across. What type are you?

The read the source commenter

Or in other words, the coder who views comments as optional. This coder takes the opinion that all the information you need is contained within the source itself. In reality they’re just lazy. I think I’m allowed to write this: I’m very much of this type.

For the most part, I actually don’t mind this style. I often prefer to work through the code line by line, figuring out what it does and how it all fits together as I go. As long the code is well written and I have a grasp on roughly how the given component works, it usually works out okay.

But there are some pitfalls. How many times have you found yourself in this position? You come across a line of code that you have no idea what it does or even why it’s there. What you do know is that if you remove it, it fixes a bug that you’ve spent hours tracing down. What you don’t know is the impact of removing the line. Will it pass without incident or will computers around the world suddenly start catching fire? See, a little explanation here wouldn’t go amiss.

So some commenting is useful. But how much?

The essay writer

This type of coder makes the assumption that everyone reading their code is an idiot. Often, the lines of comments far outnumber the lines of code. I once heard someone say that you should write your code with the intention that your gran should be able to understand it.

And here’s my problem with this style. I’m not an idiot (or at least I like to think not). And I’m certainly not your gran.

Working on a project like LiveCode, which has a very mature code base, you find that a lot of your time is spent poring over code, trying to figure out what it does and how it works in order to fix bugs. You want to do this as quickly and efficiently as possible. However, there’s nothing worse than when going to fix a bug, finding yourself faced with a swathe of green. It makes you feel like that to even begin contemplating fixing the issue you need to spend the next few hours sitting down in a darkened room getting into the author’s mindset. Only then will you have reached a point where you will be able to understand and comprehend the complexity of the  code that follows.

In reality, when fixing a bug, you want to do it as efficiently as possible. You don’t need to have a complete grasp on the full inner workings of the system. You just need to know enough to understand what the issue is and know that your fix won’t cause any further issues.

My opinion is that more significant chunks of technical documentation should be kept separate from the source code itself. If you find yourself having to write a lot of comments to explain your code, maybe the problem is with the code itself. Try and write clean and clear code. Often code that is well designed and thought out requires fewer comments and is much easier for third parties to understand.

The redundant commenter

Ahh, the redundant commenter. The only thing that annoys me more than the essay writer is the redundant commenter. I’m sure that this coder has good intentions at heart. It’s just they appear not to be able to put these good intentions to use. Take for example, the following lines of code:

    -- Repeat through each person in the address list
    repeat for each line tPerson in tAddressList
        . . .
    end repeat

As I’m sure you can see, the comment above is less than useless. Consider this: You’ve spent what feels like hours tracing down a bug, get increasingly more and more frustrated. At this point you would take any minor hint or guidance. Just a little something that might point you in the right direction. You spot a line of green. You think this is it, this is the comment that is going to make everything clear. You read it. You collapse in a heap of disappointment. At this point, I usually get up from my desk, go home and swear I’m never going to look at a computer again.

That may be an exaggeration, but padding out your code with redundant comments isn’t really helpful. It’s commenting for the sake of commenting. If a line of code is self explanatory, there’s no need to comment.

Finding a balance

So, comments are needed. But too much can be counter productive. So what’s a good balance? I generally try to stick to the following rules. Use descriptive names for your variables and handlers. Don’t be scared of verbosity, but don’t go overboard.

  • Use a prefix system for variables (e.g. local variables, parameters, globals, script variables etc).
  • For each handler, write a sentence or two describing what the handler does (not how), including a run-down of parameters it takes, what it returns and any errors it throws. If you can’t do this in a few sentences, that suggests that you may need to rethink your abstraction.
  • Comment on any blocks of code that are doing something subtle or that is not immediately obvious.
  • Attempt to make the code you write as clear and simple as possible. After you’ve got a block of code working, if you think you can rewrite it in a cleaner way, then do so.
  • If you are working on a larger project that requires further description, do this in a separate document.

These, though, are just my thoughts and opinions that have been formed over years of looking at other people’s code. I imagine that if you ever had to work through some of my code, you’d no doubt be of the opinion that I’m full of nonsense and doing it all wrong.

read more
Michael McCrearyReading other people’s code

Connections.

by Heather Laine on April 9, 2014 2 comments

This afternoon, for one reason and another, I am temporarily disconnected from the internet, and I’m finding it pretty traumatic. I’m using the time to write a blog post, but even this simple activity is hampered by my inability to look up things online, check my facts on Wikipedia, and locate suitable images to illustrate my points.

Which really is the point of today’s post. Our lives these days are governed by connections and many of the apps we write can be seen as collections of information gathered, often live, from the wonderful world wide web at our fingertips. So many apps are data driven, grabbing information as it is needed and serving it up to the end user, hot from the grill. For example, my desktop calendar has of its own volition located the calendar on my phone and now startles me daily by popping up notifications and reminders when I least expect them. In my defence, some of these events were not even entered by me, they are events created by other users whose calendars talk to my calendar, which then talks to my phone and reminds me I should now be somewhere entirely different, doing something I wish I had been allowed to forget about. Push notifications in action. Terrific.

LiveCode is excellent glue. It’s great at sticking together content from a wide variety of sources and making it available in one place (your app) in a tidy way (your lovely app interface) so that the end user gets a beautiful seamless experience. At one end of the spectrum you could pull together images from a users camera, data from a website, messages from other users and create, perhaps, a fabulous recipe app that lets you take a picture of the meal you created and share it with friends. Or at the other end it could be used to create a heavy duty app for crunching through masses of data and finding trends or specific information, with its easy database connectivity. Big Data is Big Business and LiveCode is good at it.

I find all the uses that our users find for LiveCode fascinating. These days, the apps created are rarely isolated self-contained items, they are part of our interconnected lifestyle, and participating to a greater or lesser extent in the huge global network that is the World Wide Web.

You could say LiveCode is truly live.

read more
Heather LaineConnections.

Scaling up the details

by Ian Macphail on April 8, 2014 1 comment

In the previous post, I covered the update to the graphics layer. Updating the graphics library means we can now draw stacks at any scale, which allows us to add a whole slew of new and useful features. One of which is the ability to transparently support high-density displays.

Hi-DPI support

The introduction of the Retina display to iPhone/iPad created something of a problem for apps developed for the previous generation of devices. Apps created at the fixed size of these devices suddenly had four times the number of pixels to fit into (2x width and 2x height), and although they could still display at the same size, on the higher density displays it was apparent that they were not taking advantage of the available high resolution. The reason being that the apps were drawing at the old size, and then being scaled up – giving a stretched, pixelated appearance.

Rather than create a smaller image and scale it up, in order to draw cleanly and crisp on higher density displays you need to create an image with the same number of pixels as the display. This is a problem when your app is 320 x 480 in size, and the area into which you need to draw is now 640 x 960. Without scaled drawing support in the engine you would need to manually adjust everything on the stack to appear twice as big – from the size & position of each control, to the line width of any graphics, to the font size of any text appearing in the app.

To overcome these issues we could now use the new graphics library features to implement scaled drawing within the LiveCode engine. This automatic scaling is now included as of LiveCode 6.6 and is enabled by setting the "usePixelScaling" property. On mobile devices the degree of scaling can also be controlled by changing the "pixelScale" property.

The pixelScale controls the relationship between the logical size of the screen and the number of physical pixels in the display. This is quite straightforward on mobile devices, where there is only a single display. The old pre-Retina Apple devices have a 1:1 ratio of logical coordinates to pixels, retina devices have a 1:2 ratio. For a 320×480 stack to appear at the same size on both devices it should have a pixelScale of 1 on the non-Retina device, and a pixelScale of 2 on the Retina device. This happens automatically in the LiveCode engine – the pixelScale is set on startup to the appropriate value for the density of the display.

Getting it all to work

Implementing this within the engine was pretty challenging. If everything can be scaled, then there is no longer necessarily a 1:1 relationship between the size and location of objects on the stack, and their position on the screen as understood by the operating system. Unfortunately this was an assumption made in many different areas, such as the size and location of windows, to the position of mouse movements and clicks, to the apparent size of the screen itself. The situation is further complicated by the fact that some platforms expect coordinates in terms of screen pixels (Windows, Android), and others in terms of logical screen coordinates distinct from physical pixel sizes (iOS, OSX) so we end up having to think in terms of three separate coordinate systems: logical sizes within the engine, physical pixels, and logical (or not) coordinates used by the OS.

All this means that where code could previously use the same coordinates when referring to objects on a stack, or the position of the mouse cursor within a window, now that code had to be adapted to translate back & forth from one coordinate system to another. This was made somewhat easier by the progress of ongoing refactoring work to separate out window-related functionality from the tangle of stack code that made no distinction between a stack and the window that contains it. Now it was possible to define a scale factor between one and the other, and convert coordinates at the point of passing through from one to the other.

I think this really highlights the value of the work we’ve done to split apart the engine code into clearly defined areas based on a consistent and logical identification of distinct concepts that helps collect related code together and removes the implementation details from areas that are not directly related.

LiveCode 6.6.1 is now available. This is a stable release.

Getting this release
To upgrade to this release please select "check for updates" from the help menu in LiveCode or download the installers directly at: http://downloads.livecode.com/livecode/

read more
Ian MacphailScaling up the details

Livecode.org email addresses and talking to PHP from LiveCode Server

by David Williams on April 3, 2014 2 comments

One of the things we’ve introduced recently was the LiveCode Membership product, one of the benefits of which is a livecode.org email address of your choosing. This meant that we needed to set up the livecode.org domain to use with email accounts on one of our servers, and then set up some way for the livecode.com store to communicate with it in order to set up the email accounts. This is made simpler by the fact that we make use of cPanel/WHM, meaning we can use the cPanel API for this kind of operation.

The cPanel API is written in PHP and allows you to perform a wide range of operations. The problem here, of course, is that it’s written in PHP – we want to talk to the API using LiveCode Server! So this raises the question – how do we interact with PHP scripts from LiveCode Server? This is a question that comes up every now and again for the reason that many utilities and systems are written in PHP.

In this instance, the API performs and action and returns a result (as either JSON or XML). For very simple instances where we just want to, for example, be able to get a list of all email accounts, we can set up the PHP script that performs the relevant API call, and then execute it directly using shell() from our LiveCode Server script:

...
put shell("php check_email_accounts.php") into tAccountsXML
...

This method is appropriate when we don’t need to pass information to the script, and where we also don’t need to use the CGI environment, which isn’t initiated if we execute it in command-line mode. Another way is to set up the script to handle data posted to the script:

...
post "user=" & tUser & "&pass=" & tPass & "&auth=r34l1ygr34TaU7h5tr1nG" to url("http://mail.somelivecodedomain.com/create_mail_script.php")
...

The script that the data is posted to should then be set up to take the values from $_POST and use them as parameters in the API call.
This way we also have access to the CGI environment in the PHP script should we need it. Security can be accomplished quite easily as we know where the post is coming from and can use .htaccess directives to restrict how the file can be accessed, as well as the standard types of script-based authentication we might use with this.

Ideally, in this instance, we would set up a single PHP script to which we would post the name of the desired API function and a list of parameters, which would be processed into the correct format and then passed directly into the api query function into that script. In this way we could implement a single callCPanelAPI() function in our LiveCode Server script.

read more
David WilliamsLivecode.org email addresses and talking to PHP from LiveCode Server

Examining Unicode, Part II – Digesting Text

by Fraser Gordon on April 2, 2014 11 comments

In my last article, I described how Unicode text can be broken down into its individual subcomponents: characters are composed of one or more codepoints and these codepoints are encoded into code units which comprise one or more bytes. Expressed in LiveCode:

byte a of codeunit b of codepoint c of character d

This article will explain how you can use these components when processing Unicode text.

Characters to Codepoints: Normalisation

Following the chunk expression above, the first step is breaking a character up into its constituent codepoints. As discussed yesterday, these could be in either composed or decomposed form (or even somewhere in between!). Should you prefer one particular form over another, LiveCode includes a conversion function:

put normalizeText("é", "NFD") into tDecomposed

The “NFD” supplied as the second parameter says you want the string in a Normal Form, Decomposed. For composition, you would specify “NFC”. (There are also “NFKC” and “NFKD” forms but these are not often useful. The “K” stands for “compatibility”…).

What do you think will happen when you execute the following line of code?

answer  normalizeText("é", "NFC") is normalizeText("é",  "NFD")

LiveCode will happily tell you that both strings are equal! This shouldn’t really be a surprise; when considered as graphical characters they are the same, even if the underlying representation is different. Just like case sensitivity, you have to explicitly ask LiveCode to treat them differently:

set the  formSensitive to true

With that set, LiveCode will now consider composed and decomposed forms of the same text to be different, just as it treats “a” and “A” as different when in case-sensitive mode. Also like the caseSensitive property, it only applies to the current handler.

Lets use this knowledge to do something useful. Consider a search function – maybe you’d like to match the word “café” when the user enters “cafe” – here’s how you’d remove accents from a bunch of text:

function stripAccents pInput
local tDecomposed
local tStripped

-- Separate the accents from the base letters
put normalizeText(pInput, "NFD") into tDecomposed

repeat for each codepoint c in tDecomposed
-- Copy everything but the accent marks
if codepointProperty(c, "Diacritic") is false then
put c after tStripped
end if
end repeat

return tStripped
end stripAccents

The function also demonstrates another very useful function – codepointProperty – which will be our next port-of-call.

Codepoint Properties

The supporting library that LiveCode uses to assist in some of the Unicode support (libICU) provides an interface for querying various properties of codepoints and this is exposed to LiveCode scripts via the new codepointProperty function. To use this function, simply provide a codepoint as the first parameter and the name of the property you’d like to retrieve as the second parameter.

There are a large number of properties that exist, some of which are more useful than others. For an overview of the properties that the Unicode character database provides, please see here (http://www.unicode.org/reports/tr44/). Some of my personal favourites are:

  1. “Name” – returns the official Unicode name of the codepoint
  2. “Script” – script the character belongs to, e.g. Latin or Cyrillic
  3. “Numeric value” – the value of the character when interpreted as a number
  4. “Lowercase Mapping” and “Uppercase Mapping” – lower- or upper-cases the character

 

Example output from these properties:

answer codepointProperty("©", "Name")              -- "COPYRIGHT SIGN"
answer codepointProperty("Ω", "Script")            -- "Greek"
answer codepointProperty("¾", "Numeric Value")     -- 0.75
answer codepointProperty("ß", "Uppercase Mapping") -- "SS"

Code Units and Bytes: Encoding

The LiveCode engine does a lot work to hide the complications of Unicode from the user but, unfortunately, not all software is written in LiveCode. This means that when you talk to other software, you have to tell the engine how to talk to it in Unicode. This is where text encodings come in – every time you read from or write to a file, process, network socket or URL, text has to be encoded in some way.

To convert between text and one of these binary encodings, use one of the aptly named textEncode and textDecode functions:

put url("binfile:input.txt") into tInputEncoded
put textDecode(tInputEncoded, "UTF-8") into tInput
…
put textEncode(tOutput, "UTF-8") into tOutputEncoded
put tOutputEncoded into url("binfile:output.txt")

If you are using the open file/socket/process syntax, you can have the conversion done for you:

open tFile for utf-8 text read

Unfortunately, the URL syntax does not offer the same convenience. It can, however, auto-detect the correct encoding to use in some circumstances: when reading from a file URL, the beginning of the file is examined for a “byte order mark” that specifies the encoding of the text. It also uses the encoding returned by the web server when HTTP URLs are used. If the encoding is not recognised, it assumes the platform’s native text encoding is used. As the native encodings do not support Unicode, it is usually better to be explicit when writing to files, etc.

An an aside, we are hoping to improve the URL syntax in order to allow for the same auto-conversion but have not yet settled on what it will be.

read more
Fraser GordonExamining Unicode, Part II – Digesting Text

LiveCode RTL Left edition Released

by Steven Crighton on April 1, 2014 29 comments

LCleft
Today we are announcing the release of the new LiveCode RTL edition for left handed users.

Below is an exclusive screenshot of the LiveCode RTL edition for left handed users. As you can see we have flip reverse engineered the right handed version of the platform making it now 100% accessible to left handed users.

read more
Steven CrightonLiveCode RTL Left edition Released

Examining Unicode, Part I – The dissection

by Fraser Gordon on March 31, 2014 5 comments

As I mentioned in my previous blog post, Unicode text is hard (which is one of the reasons it has taken such a monumental effort to get LiveCode 7.0 ready for release – it is now in public testing if you’d like to try it out). In order to make everything work transparently for the writers and users of LiveCode stacks, a lot has to go on behind the scenes. In this post and its follow-up, I hope to explain how some of these innards work. This first post is a bit technical but will lay the groundwork for some new Unicode text processing techniques.

The most important thing with Unicode is to understand what is meant by a character – different people have different definitions, some quite technical. Older computer software will often refer to 8-bit bytes as a character, a standard which LiveCode and its predecessors followed. Sometimes, "character" is used for the symbols defined by the Unicode standard (these are more properly termed "codepoints"). Neither of these is necessarily what a human reader would think of as a character, however.

Consider the letter "é" – that’s obviously a single character, right? Well, it depends on who you ask… Considered as 8-bit bytes, it could be anywhere between 1 and 8 "characters". Looking at it with Unicode-coloured glasses, it could be either 1 or 2 codepoints. However, in LiveCode 7, it is always a single character. If you were a Unicode geek like me, you’d call this LiveCode definition a "grapheme cluster".

Why do these different interpretations arise? If you’ll bear with me, I’ll take it apart piece-by-piece.

First comes the codepoints. The Unicode standard defines two types of representation for accented characters known as "composed" and  "decomposed". Continuing with "é" as our example, Unicode would call this U+00E9 "LATIN SMALL LETTER E WITH ACCUTE" in its composed form. In its decomposed form, it would be a U+0065 "LATIN SMALL LETTER E" followed by U+0301 "COMBINING ACCUTE ACCENT". Basically, composed versus decomposed is the choice between accented characters being characters in their own right or instead being an un-accented character with an accent atop it. Conversion between these forms is called "normalisation" and will be discussed in my next post.

Next comes the variable number of bytes that are used to store these codepoints – this comes down to how these codepoints are encoded. Sometimes, old 8-bit encodings have a single byte to represent a particular composed character. Unfortunately, these encodings can only represent 256 different characters so Unicode encodings are used instead. The particular encoding used within LiveCode is UTF-16 (but this is internal to the engine and isn’t visible to LiveCode scripts).

The UTF-16 encoding uses 16-bit values to store codepoints, termed "code units". This extra term is needed because although many languages have all of their symbols representable using a single code unit, a number (including Chinese) need two code units per codepoint for certain characters, due to the large number of symbols within the language. Because of this, a codepoint can be either 2 or 4 bytes in length when encoded with UTF-16.

Other common text encodings are:

  1. UTF-8. Uses between 1 and 4 bytes to encode codepoints. Common on Linux and MacOS X systems.
  2. UTF-32. Always uses 4 bytes per codepoint. Trades space efficiency for simplicity.
  3. MacRoman. Always 1 byte, non-Unicode. Legacy encoding on most MacOS systems.
  4. ISO-8859-1. Always 1 byte, non-Unicode. Legacy encoding on many Linux systems
  5. CP1252. Always 1 byte, non-Unicode. Legacy encoding on many Windows systems.

As you can see, there is a fair bit of complexity behind the transparent Unicode support in LiveCode 7. In my next post, I’ll show you how you can take advantage of knowing how it all fits together.

read more
Fraser GordonExamining Unicode, Part I – The dissection

LiveCode 6.7.0 DP1 Released

by Ben Beaumont on March 28, 2014 5 comments

We are pleased to announce the preview release of LiveCode 6.7.0 DP1.

For those of you that don’t know, LiveCode releases come in different stages.

DP – developer preview (feature incomplete likely to be unstable)

RC – release candidate ( feature complete, likely to be quite stable but is not considered the final stable release)

GM – gold master ( feature complete stable release)

The primary focus of this release is cocoa support. This required us to re-port LiveCode to the newer Mac platform API’s (cocoa). As a result, there may be some instabilities on Mac OS. Once again, thanks to those who helped with alpha testing to iron out the major bugs. 6.7 has now passed all automated tests and a first pass community test. We are aware of a sporadic crash related to audio which we’ve been unable to replicate or trace. 

Release Contents

  • Cocoa Support
  • New revBrowser WebKit external (Windows, Mac) with new bi-direction javascript to LiveCode communication.
  • Mobile In-App Purchasing support extended to Amazon * and Samsung stores
  • Clipboard data ‘styledText’ array accessor
  • OS 10.5 (Leopard) Support dropped
  • 4 bug fixes: 
    • 11975 – "import snapshot from rect …" only imports part of the screen on Windows
    • 11946 – iOS 7.1 Simulator doesn’t remember device type when launching using ‘Test’
    • 11917 – Setting the label of an option or combo-box does not update the menuHistory.
    • 11808 – pixelScaling not enabled on Windows Commercial edition

* Our in-app purchasing implementation for the Amazon AppStore is unfortunately restricted to commercial license holders only. This is due to the Amazon PML license being incompatible with the GPL. If you wish to use the Amazon in-app purchasing features of LiveCode you will need to be a valid commercial licence holder.

For full details of features and fixes please see the release notes: http://downloads.livecode.com/livecode/6_7_0/LiveCodeNotes-6_7_0_dp_1.pdf

Known Issues

  • We are yet to implement an AVFoundation version of the player object and switch the engine to weak link to Quicktime. This is expected for DP2.
  • Performance on High DPI system slow from 6.6 onwards. Our head of technology posted about this on our blog last week. We plan to refine his prototype and include during the 6.7 cycle. For those of you who missed the post you can read it here: http://livecode.com/blog/2014/03/18/hi-speed-hidpi/.
  • Sporadic crash related to audio (not reproducible at present).
  • Field navigation with arrow keys in WebKit browser input fields. http://quality.runrev.com/show_bug.cgi?id=12047. 

Testing
As always we appreciate very much all those who help us refine these early releases. 

  1. If you are a browser object user, we would appreciate you testing your projects with the new revBrowser external. You can create both old and new WebKit browser instances. Please see the release notes for details of how to create the WebKit variant. The original revBrowser object remains unchanged.
  2. If you are a mac users please test all your projects by opening them and seeing how they behave in the new windowing system. Your apps will now be rendering entirely in the cocoa windowing framework so you’ll notice subtle differences.
  3. If you have a mobile app that uses in-app purchases please see the release notes for details of the new in-app API. You will need to make some minor changes to your projects to ensure that your in-app purchases remain functional with LiveCode 6.7. The new API is cleaner and simpler as well as supporting the two additional stores and subscriptions. 

Reporting Bugs
If you encounter an issue with this release please submit a bug report to our quality centre: http://quality.runrev.com/enter_bug.cgi

Get the release
To upgrade to this release please select "check for updates" from the help menu in LiveCode or download the installers directly at: http://downloads.livecode.com/livecode/

Resources
For lessons related to the new in-app purchasing api please see: http://lessons.runrev.com/m/19606

THERE ARE INSTABILITIES IN THIS PREVIEW RELEASE so please take care to use backups of your stacks when testing.

read more
Ben BeaumontLiveCode 6.7.0 DP1 Released

Recent Posts

Recent Comments

Tags