NickTelford.net

There is an interesting discussion on the use of the term “login” as a verb, part of a much wider discussion on colloquial terms often misunderstood to be verbs, that got me thinking about the proper terms for such actions.

“Login” is just one of many offenders (many of which originated on the Internet) that could easily be replaced with verbs that make much more sense.

Readability

Of course, there’s a strong argument that words such as “login” and “checkout” have well-defined, verb-like connotations that readers’s are familiar with. So it’s often wise to sacrifice absolute grammatical correctness in order to communicate better with your readers. After all, the purpose of a language is as a well defined, but constantly evolving communication protocol.

However, there are ways in which you can ensure grammatical correctness without misleading your readers.

Grammatically Correct Software

In the context of software development, “readers” are the users of your software. Understanding how users perceive actions within your software (and optimising it) is a crucial aspect of development that is often overlooked. Using correct grammar can help a lot by providing users with a language that is familiar and un-obtuse. Users should never find themselves thinking “what does that mean?”.

So we need to be both grammatically correct, but colloquial enough that users don’t have to think too hard about what they’re doing. Lets see if we can apply this to a couple of common “anti-verbs”.

“login”

As the notaverb.com reference for “login” points out; “login”, while not a verb, can be a noun. This is useful as it allows us to use terminology that user’s are already familiar with in order to prevent them from getting lost.

So if “login” is not a verb, what is? It’s suggested that “log in” is appropriate, but since this is a verb/adverb combination this doesn’t really fit the bill as it implies that you are “logging” in an “in” way. Even if this is grammatically correct, it’s quite vague: what or where is “in”?

I’d propose that, in the context of software, an appropriate verb would be to authenticate. Authentication implies that you are being recognised (or rejected) by an authority – in the case of software, the application itself.

Note: There are often two software processes involved in “logging in” – “authentication”: checking the authenticity of a user and; “authorization”: ensuring a user has authority to do something.

It’s good practice to disambiguate these terms internally (in the software code and audit logs etc.) but wise to make the latter transparent to users; a user should only be concerned with authentication.

The problem with “authentication” as a verb is simply one of complexity. Big words scare people.

We can use the noun form of “login” to provide user’s with a grammatical cue that they’re familiar with, but what is a “login” if it’s a noun? Simple, the “username”.

“username” is a word I’m strongly opposed to as it’s (in my opinion) not really a noun; it is two nouns squashed together: a “compound noun” if you prefer. More specifically, it is the “name” of the “user”, although the actual name of the user is often quite different – so how do we disambiguate the two?

The solution is simple: ditch the term “username” in favour of the proper noun “login”.

Using these ideas, here’s how an authentication process may appear to a user in a way that’s both accessible and grammatically more accurate:

Authentication
Please enter your login and password:
Login: __________
Password: __________

It seems to have become part of modern internet culture to define new words, often that defy traditional language conventions, in order to describe something new and exciting. This is not only unnecessary, it makes technology obtuse and less accessible – particularly to the older generations.

At the end of the day, technology is meant to innovate, liberate and empower users – not confuse them with unfamiliar words.

I’ve been doing a lot of multi-process and signal programming PHP lately, and I found myself wondering which signals it’s possible to intercept and handle in userland PHP. Of my findings, the most interesting was that you can trap SIGSEGV (“segmentation fault”) and handle it yourself.

By default, when the kernel raises a SIGSEGV on a PHP process, PHP intercepts the signal and handles it by simply printing “Segmentation Fault” to stderr (standard error) and the process immediately exits. This is understandable behaviour, but in most applications, especially large ones, it’s useful to know what it was that caused the segfault to be raised so you can address the problem.

So I found myself wondering if it was possible to trap SIGSEGV and gather some debug information about it before exiting, and discovered that it’s much simpler than it sounds:

<?php
/**
* Demonstrates signal handling to trap Segmentation Fault using userland PHP.
*
* Useful for debugging larger applications that occasionally generate
* segfaults.
*
* You are free to modify and redistribute this code without attribution.
*
* @author Nick Telford <nick.telford@gmail.com>
* @copyright Nick Telford (c) 2010
*/

// you need this towards the start of your application in order for signal
// handlers to be executed
declare(ticks = 1);

/**
* Signal handler for segmentation faults.
*
* Since a segfault indicates a memory problem, it's wise to keep this separate
* from other signal handlers and to have it do as little as possible.
*
* Also, since there's a memory problem, this should call exit(1), otherwise
* you could end up with unpredictable behaviour. Only avoid exit(1) if you
* *really* know what you're doing.
*
* @param integer $sig The UNIX signal, will be SIGSEGV for a segfault.
*/
function handleSegfault($sig)
{
    // note: unless you're running the CLI SAPI, this will be sent to the
    // browser, fwrite() it to STDERR instead or better yet, log the info
    // somewhere (a file or syslog) for later analysis
    echo "Segmentation fault, printing backtrace:\n";
    debug_print_backtrace();
    exit(139);
}

// attach the segfault handler
pcntl_signal(SIGSEGV, 'handleSegfault');

// tests the segfault handling by generating one
posix_kill(getmypid(), SIGSEGV);

Update: I’ve changed the exit code to 139, as processes terminated by a UNIX signal should use an exit code that is the signal number + 128. The exit code for processes that terminate due to SIGSEGV is 139.

As my notes in the code suggest, you shouldn’t merely echo the information out, as by default it is sent to stdout (standard output), which any SAPI handling web requests will send to the browser. Something strongly inadvisable.

Instead, you’ll most likely either want to output the information to stderr (using fwrite()) or log the data using your application’s logging layer. It’s important that you execute as little code as possible, especially memory operations, as a segmentation fault indicates memory corruption that could have unpredictable effects on your application.

In PHP 5.3.0 PHP’s handling of signals was changed from implicit, using declare(ticks = n) to instruct the interpreter to automatically dispatch pending signals after n lines of code are executed; to explicit, by calling pcntl_signal_dispatch() yourself. Whilst the new explicit process is more flexible and provides for better performance, it does have the potential to decrease the durability of your application, especially if you’re trapping SIGSEGV, because the application will continue to run until you call pcntl_signal_dispatch(), even though memory corruption has occurred.

Finally a note about performance in PHP < 5.3.0: using declare(ticks = 1) tells PHP to check for pending signals after it executes every line of code. Obviously this adds an overhead (albeit a small one) to your application. For that reason, it's probably wise to have this disabled in production environments.

One of the keys to writing good and portable code is clear and concise documentation. Most programmers have a tendency to dislike documentation – thinking of it as an ancillary task, to be written once the bulk of the programming has been done. This attitude yields low quality documentation which can have some serious problems.

All but the smallest of projects have the problem of new programmers having to understand code that others before them have written, a task made harder when you encounter documentation like this:

/**
 * doSomething
 *
 * @param mixed $id
 * @param mixed $name
 * @param mixed $thing
 */
public function doSomething($id, $name, $thing)

If you’re wondering what’s wrong with this documentation then you definitely need to keep reading.

This is PHP code documented with PHPdoc. Of course, other languages/tools will differ, but anything based around JavaDoc will be similar to this.

How to write good documentation

First off, the format for a PHPdoc method doc-block is as follows:

/**
 * <short description>
 *
 * [<long description>]
 *
 * @param <type> <variable> <description>
 * @return <type> <description>
 */

Now, looking at our example above, we can see several glaring problems:

• “doSomething” is the name of the method, not a short description. You don’t need to write the name of the method anywhere in the doc-block as PHPdoc can read it from the method signature.
• There is no long description – while this is optional, non-trivial methods should always have a long description so that anyone can understand the method’s use without looking at the implementation code.
• None of the parameters have any type information – while it’s possible that this method does accept mixed types for all the parameters, it’s unlikely. PHPdoc can’t infer the type from the method signature (unlike JavaDoc) so you need to specify the type here.
• None of the parameters have a description – Parameter descriptions aren’t optional. If you include an @param tag, you may as well write a sentence that describes the parameter.
• There is no @return tag – while this method may not return anything, many do. You should always document the return type and conditions of a method. For methods that have a more complex set of conditions on their return value you may want to elaborate in the method’s long description.

As it stands, the example I gave above provides no information about the method that couldn’t be inferred from the method signature. The doc-block might as well have been omitted entirely.

Good documentation verbosely describes a method’s use, it’s inputs, outputs and their conditions. Reading the documentation for a method should be all a programmer needs in order to understand what it does and how to use it. If you want to check your documentation, ask a friend or put yourself in the shoes of another programmer and read the documentation through without looking at the code.

When to write documentation

One of the main causes of bad documentation is that many programmers either fill in some documentation after they have written their code or omit it entirely.

It’s safe to assume that usually, when writing a method/function/procedure, programmers already know what they want it to do and how they want it to work. The best process I’ve found for writing a method is:

• Think about what it will do and how it will work (or look at the design document)
• Write the method signature (the declaration) – e.g. public function doSomething($id, $name, $thing)
• Write the documentation, in full.
• Write the method body – e.g. in PHP/Java/C# everything between { and }

Using this process you will have full documentation for the new method before you’ve even written it! What’s more, you can refer to your documentation while writing the body code, ensuring you get things right. This is especially effective in a test-driven development scenario where you are designing all your methods to pass a set of unit tests.

Documenting body code

Once you get used to the process, documenting methods/functions/classes becomes almost second nature. But there’s a separate art entirely to documenting body code – the code inside the method/function/procedure.

The trick to it is not to over-comment your code. Code that has every single line preceded by a comment is useless, especially when those comments look like this:

// check the result is not null
if (!is_null($result)) {
    // add result to the return array
    $return[] = $result;
    // increment the count
    $count++;
}

The problem with this is that the comments add no useful information from the code. In fact, every line of that code is “self-commenting”. It would instead be more useful to comment this block of code as a whole, to describe what its doing from a higher level:

// add any results
if (!is_null($result)) {
    $return[] = $result;
    $count++;
}

Of course, without the greater context of the rest of the code, this still doesn’t make much sense, but you can see that it is immediately more legible – there are no unneccessary comments cluttering up the code.

The trick to commenting body code is to divide the it up in to relevant chunks and comment blocks that are not immediately obvious. Good candidates are loops and branches (if/while/for etc.) as they naturally group code in to a block and usually perform one or two related operations.

This concludes my crash course on code documentation. Please leave any questions, suggestions and criticism in the comments.

After we launched TwitOrFit we noticed a rather surprising backlash within the Twitter community. Many users were unhappy with trusting a web-based service, such as TwitOrFit, with their Twitter credentials – and rightly so – giving out your password is one of the cardinal sins of the online society we live in.

However, many people don’t seem to realise that without both their Twitter username and password, there’s very little external services can do with Twitter. And this is the crux of the problem – Twitter’s API requires you to send the username and password of the user with every API call.

On the surface, this doesn’t seem so terrible, after all service providers may request the user’s password then throw it away after the API call has been made – but one of the important points to remember is that Twitter’s API is not located on an SSL secured server. So any calls made to Twitter’s API is made with the username and password in the HTTP header sent in plain text.

fav.or.it was recently lambasted by a blogger for doing exactly this (I’m unable to locate the URL), and we are soon going to fix the problem by launching an update that will include an SSL secured user area. Still, it amazes me that such a high profile website has been totally overlooked when it comes to this gaping security hole.

The solution to the problem is simple: Twitter, and many other API providers, need to stop requiring the password to be sent with each API call. Instead they should adopt one of the many approaches designed to circumvent this problem, be it OAuth, a challenge/response system or even a full blown token-based session system.

My favourite approach is currently LiveJournal’s challenge/response system. From a developers point of view it’s very straightforward to use and very secure. In theory, it can also be used to allow users to revoke the permission of an application.

Twitter are supposedly working on an OAuth implementation with plans to drop support for the Basic Auth 6 months after it goes live. Unfortunately, sources tell me that they’re making very slow progress, so we can’t hope for anything soon.

Update: Last night, approximately 30 minutes after I wrote this post, Twitter announced the opening of their private beta for their OAuth API. Apparently, my source got his information about 6 months ago… Is anyone aware of a sauce or condiment that goes well with my hat?

Since the launch of the Facebook Platform earlier this year many people have been writing applications for the social networking site. Some good, some bad and some very ugly.

However, something that has probably slipped most people by is exactly how useful the Facebook Platform is to Facebook themselves. Most of the core elements, the Wall, Groups, Events, Photos etc. (but not Profiles and Pages) are all in fact applications that run on the Facebook Platform. Most people don’t notice because they’re enabled by different, but it affords Facebook many advantages.

For a start it enables them to create the Platform using use-driven development. While I don’t know whether this is true, it’s certainly a brilliant opportunity to aid development. I also makes the entire system far more modularised – by decreasing the number of things that are part of the core of Facebook, they’ve reduced the amount of code that has to be maintained by the core Facebook team. Problems with the default applications, for example, a bug in the Wall, can be easily isolated and therefore fixed quickly and easily.

As with bug-hunting, modularisation allows them to very quickly create new features without having to dabble with the core code and potentially break one of the most popular websites in the world. New features can be tested by releasing it as a non-default application and, once it has been put through its paces, deployed en-mass.

All of this gives Facebook the opportunity to comepletely crush rivals like MySpace, and with relative ease. Obviously, they’re not there yet, but they launched “Pages” only 4 days ago, alowing groups/organisations to setup specialised profiles, and already around a quarter of my favourite bands have their own pages.

Together with the clean look and easy to use interface, Facebook’s extensibility and modularity has exactly what it takes to bury MySpace.

This has me thinking: Can this computing model of abstraction and modularisation be applied as a general business model to real world products? And if it can, can it with much success? The answer to both questions is probably “no”, but I’d certainly be interested in finding out.

I’ve always hated the idea of of using nothing but Microsoft products on a computer, about as much as I’ve always hated the idea of owning a laptop. So, after finally having taken the plunge and bought myself a cheap little number – pre-installed with Windows Vista – I’ve decided to see what life would be like if all my software was Microsoft.

Obviously, I will be installing some non-Microsoft software – Adobe Flash Player was among the first things I installed – but my productivity software will largely be developed by Microsoft.

I started by setting up the native Vista applications – Windows Calendar, Windows Contacts and Windows Mail. I couldn’t help but notice that Windows Mail actually seems to handle my various IMAP accounts better than Evolution – a supposed rival to Outlook.

The integration between Calendar, Contacts and Mail is intriguing, I can’t pass judgement until I’ve used them for a few weeks, but if it works well it’ll certainly increase my productivity.

On the subject of integration, I know they’re legally bound not to bundle Windows Live products with Windows Vista but it does strike me as odd that the Windows Live crew hasn’t explored the possibility of integrating better with Vista.

I would love to see Windows Live Messenger automatically tie my Live account to my system account, using it’s contact details and display picture without having to select one myself.

Similarly, it’d be nice for my Messenger contacts to be added, in some form, to Windows Contacts. Even if they were fairly basic, it would give me a starting point to go through and add more details for each contact.

Windows Live Writer, I must admit, is one of the better Windows Live products. It’s one of the best desktop blog publishing tools I have ever tried. Upon opening it I was prompted for my blog address, username and password. Writer automatically set everything up using just these 3 pieces of information. That’s simplicity.

Windows Vista itself works like a charm. That’s right. No driver hell, no sluggish operations, no crashing and very little nagging from the controversial User Account Control (UAC).

Reflecting upon my move to Windows XP back in 2001 – just after its release – this experience is much smoother. While critics have lambasted the operating system for its poor compatibility, it is miles ahead of the situation Windows XP was in this long after it launched.

While it’s certainly not the best thing since sliced bread, and is not going to cure cancer (although it may play a part), I feel confident that Windows Vista and most mainstream applications will be stable enough for most companies to roll out once Service Pack 1 is released next year.

Finally, to everyone who immediately discredited Windows Vista before using it for a week or two, I pity you. Sure it took them far too long to produce it, but that doesn’t change the fact that it’s significantly better than Windows XP. I’m not going to explain why, Vista’s critics will just have to use it to find out.

The title for this post is a little misleading because what I’m proposing is both a frontend and a backend for configuring FUSE-based filesystems.

This started off with me spending 2 days hacking together a small PyGTK tool to mount SSHFS filesystems. It quickly became apparent that my limited PyGTK skills had left me with some pretty ugly code. So, with a little more experience under my belt I decided to start again.

However, this time I’m not just going to tackle the mounting and unmounting of SSHFS filesystems – instead I plan to build a tool for mounting and unmounting any FUSE-based filesystem (whether it’s local or remote) and have it automatically mount selected filesystems on start-up.

I now have a basic specification which calls for the following major components:

• A new file, ~/.fusetab, that will contain definitions for all your FUSE-based filesystems.
  • It will need to contain: FUSE driver (e.g. sshfs), filesystem path (local or remote), mount point and a flag to determine whether it should be automatically mounted on startup.
• A PyGTK frontend to manage the filesystems defined in ~/.fusetab.
• A fast, simple Python script to parse ~/.fusetab on startup and automatically mount the specified filesystems.
• A shared library, likely a simple Python class, that encapsulates a filesystem with methods to mount, unmount and get the mount status.

There will need to be hooks defined in the shared library that allows drivers to define additional creation and pre/post mount/unmount behaviour (i.e. when mounting over SSH for the first time it should attempt to append your local ~/.ssh/id_rsa.pub to your remote ~/.ssh/authorized_keys in order to remove the need for a password on-mount).

FUSE drivers will also have to instruct the shared library exactly how to mount filesystems. This I haven’t fully researched but I’m hoping that the Python FUSE bindings themselves will have something to do this elegantly, otherwise I’ll have to have the driver define the CLI program to execute for mounting filesystems.

If anyone reading this has any thoughts on this, especially regarding its design, please comment, I’d love to hear from you.

The Gnome desktop has for a long time, been a collection of related projects. The official distribution of Gnome generally includes only those projects that have been declared “a part of the Gnome desktop” – anything that fits well and complies (loosely) with the Gnome Human Interface Guidelines (HIG).

It’s a shame in many ways because it leaves the Gnome desktop feeling incomplete. Recently I’ve been thinking long and hard about the Gnome control panel applets (cutely abbreviated “capplets”) and how best to tackle them. Generally, I’ve found them to be a bit fragmented, with often related options in totally different capplets or with seemingly vital options missing entirely.

That’s not to say there’s a lack of good software and developers out there making such programs for Gnome, but unfortunately they appear either unwilling or unable to integrate this work in to the Gnome desktop itself.

Case in point: Today I found out about sysinfo, an application for displaying useful system information in a user friendly way and is miles better than the standard “Device Manager” capplet. It’s written for Gnome in GTK+, so in theory, there’s no reason why it shouldn’t be a part of the Gnome desktop. It would require fairly minor changes to integrate it in to the Gnome desktop as a control panel applet so why not?

Sysinfo isn’t alone, there is a multitude of applications and especially applets that provide much needed functionality and yet hasn’t been included in the Gnome desktop. All that would be required is someone from Gnome to contact these developers and say “Hey, you’ve got a pretty good thing going there, with a few small changes/additions this’d fit great in to the Gnome desktop.”

If I was approached by a seasoned Gnome-er and asked to incorporate my application in to Gnome, I’d leap at the chance. Especially if it’d fill a whole and make the Gnome desktop just that little more complete.

I’m in the process of moving my blog over to Wordpress now that we’re with a new VPS provider.

I’ve mostly ported the theme and all the old posts, but unfortunately I don’t think I’m going to be able to post the comments.

The theme is pretty slap-dash at the moment. It hasn’t been tested in anything other than Firefox 2 on Linux so it’ll likely be a little broken, especially on ancient installations of IE.

Windows Vista’s UAC (User Account Control) has sparked much controversy on the internet. The simple fact is that UAC prompts the user far too much, something everyone agrees on, but is it really the fault of UAC?

UAC, in principle, is a good step towards making Windows a better and more secure operating system, unfortunately in practice it proves more of an irritation to users, who find themselves clicking “continue” out of habit. Reminiscent of software installation licence agreements.

OS X and most desktop Linux distributions have been using a similar approach to allow temporary administrative access for years to much success. However, both of these require more from the user than UAC, needing a password to “continue” whereas UAC merely prompts the user to click a button.

The problem is that administrative access is required by far too much on the Windows platform. Each time something requests administrative access. Want to delete a shared shortcut from the start menu? You’ll need administrative access for that! How about playing Battlefield 2142 online? Sorry, Punkbuster requires administrative access (why!?).

The truth is, it’s not UAC that’s the problem. It’s all the various programs for Windows that assume and have always assumed that they have full administrative access to the machine. It’s a long standing loop-hole that Microsoft have finally closed and now developers have to actually put some thought in to their software before coding.

Of course, Microsoft themselves have this lesson to learn as many actions in Windows Vista require administrative access when they probably shouldn’t.

Hopefully, in time everyone will learn that they’re not in charge of the computer. The user is.