standards

The concept of code smells is admirably applied to CSS in this blogpost. CSS is rarely considered as a "proper" programming language, so it's nice to see it treated with as much rigour as other languages receive.

However, the more I read it, the more I worry that the biggest code smell I come across in CSS isn't even mentioned; worse, it's actually demonstrated, by the very CSS examples and accompanying text. You see, I'm worried that nowhere in the article is a single mention of comments, their use or their abuse. Meanwhile, over around 100 lines of quoted code, there are only two copies of the same comment, a comment that adds so little to the reader's understanding that it exemplifies bad comments.

I would suggest if there's one cross-platform, cross-technology "code smell" then it's not commenting your code. But certainly there's a belief I've encountered among frontend developers that good CSS is, by its declarative nature, self-explanatory; that LESS or SASS, combined with judicious attention to nesting, mean that you don't need any accompanying human-readable documentation. Maybe that's true; but if we're talking about code smells, then: if you discovered this culture in any other programming community, wouldn't you do a double-take?

Of course, the brilliant programmer can in theory code without comments; well-written, lucid code can be readable enough that extra human documentation isn't required. But who's that good a programmer, all the time? I'm certainly not, especially when it comes to CSS. What proportion of CSS authors, with a keen eye for visuals and understanding of how to achieve them, are also really good programmers, in the sense that they understand and appreciate dependency, modularity, refactoring, maintainability, etc.... Meanwhile, how does the Dunning-Kruger effect influence the opinions of the very worst programmers, bolstering their belief that they too are good enough to code without comments? How much CSS work is done by designers, or junior developers, who can be skilful in their own fields, but not trained to write good code?

The simplicity and accessibility of writing CSS means that, if we're not careful, we will all end up sitting on the plateau of mediocrity, because a plateau is a confortable place to be. Rigorous coding, through attention and attendance to code smells, is a great way to start to climb the foothills of expertise. So we can't let the assumptions of the prevailing culture keep us on that plateau: let's train ourselves to comment our CSS, until we're good enough to train ourselves not to.

In the spirit of getting it out there, I've now begun implementing a columnar grid system on my site. As discussed in Mark Boulton's excellent talk at DrupalCon Paris 2009, and reported briefly in my live notes from the conference. such grid systems are a basic underpinning of consistency and visual clarity on a site. You start at the grid, then decide how your actual page elements are going to fit into it.

This means you can begin with a columnar grid of five evenly-sized columns (such as de Standaard's website, one of Mark's examples) but then build e.g. a two- or three-column layout on top of it (or, as de Standaard seem to have done, a sort of 2.5-column layout). Your columns need not be evenly spaced, and you don't even need to use columns at all: modular and hierarchical grids can be used to great effect, although they suit print somewhat more than the web. It's hard to overstress the importance of helping the user to make these implicit connections: the grid gives your site visual predictability, and means your users are more likely to find what they want; it's implicitly tied to both visual aesthetics and also basic site user experience and usability.

I decided to have a seven-column grid for this site, as that gave me a lot of flexibility in page layouts: a three-column page could be 2-3-2 or 1-5-1. Consistency of field combinations is important, but as with the Guardian's website, as long as your underlying columnar lets users make that implicit connection without realising it, you can still push the boundaries of inconsistency on top of that. I decided on a field width of 124px, with a 15px margin between fields. Seven columns and six margins make 958px, which is comfortably close to the equally comfortable yet ultimately arbitrary 960px limit I'm personally used to.

So far, as I've not exposed much of the site, you won't see the effect of a lot of this, although the blog index should now be broadly following a 2-3-2 layout. When I've got the full content for the finalized IA in place then you should see more of the effect of being able to vary page layout while sticking to the seven-column grid. It looks scrappy now, and will probably look scrappy then---I'm not exactly a perfectionist when it comes to design---but I'm far prouder of it than any other site design I've done from scratch.

As the Drupal 7 code freeze approaches, D7UX is gearing up for final rounds of testing: like much of Drupal's collaborative structure, this will be crowd-sourced. Get involved! You can help Drupal usability!

Anyway, Leisa discusses the next steps to be taken:

a) we need to finalise scripts and make them available to people who wish to conduct testing
b) we need to resolve the issue re: a testing theme, and
c) we need to ensure that drupalusability.org is ready to receive feedback from multiple sources

I'm pretty late to the full-on D7UX party, but tangential to (a) it just occurred to me that we would find it useful anyway to have the Verity and Jeremy user "sketches" in a more persona-like format. That way, it'd be easier to "read" the scripts in the mindset of Verity or Jeremy, and get more of a feel for whether or not their choices and observations are believable within their character.

Below are Verity and Jeremy, in a more structured breakdown similar to the one Torchbox use for in-house user personas. (I've used a bit of artistic licence to pad them out a bit, but they probably still should be considered far more like sketches than personas. As there's only two of them they have to cover quite a lot of experiential "ground" as you run through the test scripts, so they're bound to be a bit vague.)

Content creator

Name

Verity

Age

Late 20s

Job

Part-time administration assistant for a cancer support charity

Experience

• Not a developer
• Proficient with the MS Office Suite (Word, Excel etc.)
• Uses Facebook and email
• Hasn't really used Macs
• Doesn't "get" things like Twitter or Spotify

Motivation

• Verity works part-time while she completes her Social Care Diploma
• Website is one of many tasks in job
• Writing content, let alone building a site, isn't high on her career priorities
• Update "news" every week and small ad-hoc content updates
• Often interrupted by the phone and other staff while she is updating the website
• IT consultant that Verity can call: but she likes to avoid doing this

Summary

Verity wants:

• To be able to complete her website updates quickly
• Straightforward workflows, without her getting confused
• confidence that she’s knows where she is and what she’s doing at all times

Non-technical site builder

Name

Jeremy

Age

35?

Job

Social software consultant

Experience

• Not a developer
• Researched MySpace, Bebo, Facebook etc. for job
• Knows of YouTube and alternatives e.g. Vimeo
• Blogs, uses Twitter, photos on Flickr
• Has a smartphone?

Motivation

• Works with medium to large organisations to help them understand how social tools could help
• Recommends tools that they should use and how they should be implemented
• Frustrated because it is difficult to customise existing tools to suit his clients
• Would love to have the ability to ‘build’ a site that would meet his client’s requirements
• his technical skills are not great – for example, he can edit some PHP code; he understands what CSS is and what it can do, but he’s never written much himself.

Summary

Jeremy wants:

• to build rich and flexible sites
• easily discoverable functionality
• freedom from PHP code or Drupal internals

Those of you who subscribe to the Oxford Geek Nights Google group hopefully need no reminder that Oxford Geek Night 13 is on Wednesday 15 July. But, more excitingly, the two keynotes are now confirmed.

Bruce Lawson, Open Web Standards evangelist at Opera, is no stranger to Oxford Geek Nights, and covered new developments in accessibility back in OGN10. This time he'll be discussing the forthcoming new standard for hypertext markup, HTML5, and what effects it will have on web-browsing as we know it.

Andrew Walkingshaw, co-founder of Inkling Software, will present the rise (and further rise) of their service for data visualization and storage, Timetric. He'll also be discussing recent work by the Guardian which has incorporated Timetric visualizations, including a recent article on the relative purity of illegal drugs seizures over time.

We still need microslot talks, though, so if you're interested then do volunteer.

Via Sean McGrath comes a reasonably lucid and comprehensible redux of the argument about of whether or not the XML standard should (or should have) stipulated draconian error handling. I hope I'm not misrepresenting Avery when I boil a lot of it down to his three broad "real-world" examples to this:

1. Not well-formed XML, produced by a legacy application that takes ages to fix, is rejected by draconian parser
2. Not well-formed XML is accepted by a permissive parser
3. Well-formed XML is accepted by draconian parser

and I hope he's also happy for me to then state that his argument consists broadly of the suggestion that 1 and 2 are together more likely than 3, hence permissive parsers obtain for you the lion's share of the "real world" parsing instances; or, if you prefer, via a slightly more complicated profit-and-loss argment, that making your parser permissive, and sanctioning permissive parsers, contributes a lower overall cost through lumbering us with poor legacy applications, divided up among all the parsing events, than having to fix those legacy applications.

However, an application of Postel's Law to the process of implementation should not be confused with being able to apply it to the original specification. And besides, do those examples really portray the real world, nearly twelve years after the argument first took place? How much XML is out there, and how much of it is bad XML, and how much of it remains bad XML for long enough for it to cause a problem? I don't think it's clear that draconian error handling in the wild has held back RSS syndication, Google Maps, web services, or RDF so much as that, beyond a certain tipping-point (say, 2002?) they've ensured the rapid takeup thereof (with the possible exception of RDF until recently, for its own reasons).

XML is unbelievably popular today, so popular and routine in its use that you almost don't know it's there in most applications. and I think---purely from my own experience---it's plausible to suggest that that's at least partly because consumption of XML is easy; in turn, this is because basic production quality is enforced.

HTML (SGML) is a format (specification) that, because of its messiness (its complex rules), its parsing permissiveness (its potential for misunderstandings), and a whole host of cultural reasons (ditto), was terribly hard to write reliable consumption software for. Even now, there's around half a dozen good browsers, and in part that's surely because of the entry barrier to writing browsers: permissive parsing of real-world mistakes remains a complex task.

I also have dim and partial knowledge of SGML in the old-skool publishing industry, where a licence for fully-featured SGML software could set you back tens of thousands of pounds six or seven years ago, and that price didn't seem to be heading down under market pressure. In comparison, XML parsing is cheap, easy, and ubiquitous. There are free and open-source CMS and blogging packages that can do it; I have access to dozens of command-line tools that can do it; publication, syndication and webservice consumption are things that happen, almost as though nature intended it that way. A lot of that must surely be down to XML's combination of rule simplicity and parser rigour. As Dave Winer says on the subject of Postel's Law and XML:

I yearn for just one market with low barriers to entry, so that products are differentiated by features, performance and price; not compatibility. Compatibility should be expressed in terms of formats, not products.... Anyway, the other half of Postel's Law is just as interesting, but so far no one is commenting. Think about it, if everyone followed the second half, the first half would be a no-op. You could be fully liberal in an afternoon or less.

Mark Pilgrim's history of draconianism versus tolerance seems to consist of a lot of tolerantists pontificating about what they've decided the "draconian" argument is: I can't believe that Tim Bray, even if he really were a lone voice, would have been such a reluctant paper tiger. But like the 1997 tolerantists, I've thus far waded in with my own interpretation of events. And despite dealing with XML on a daily basis, I find that during so many of the tasks I have to accomplish the XML layer is able to fade almost completely into the background.

Of all the problems I encounter at work well-formedness of XML happens very rarely, compared to those concerning the quality and stability of my own algorithms, application control flow, scaling and coping with heavy load, and logging and bailing out. Whether XML's ease of use is in 2009 is a result of the small rule set in XML making well-formedness easy, or the initial decision in favour of draconian parsing, all decided back in 1997, we'll probably never be able to tell. All that's certain is that there'll always be opinions about it, and somewhere in the rambling above is mine.

Drupal's Form API handles so much work for you that you'd be a fool not to use it as much as possible. This code snippet:

function myform_some_form($form_state) {
  $form['text'] = array(
    '#type' => 'textfield',
    '#title' => t('Your submission'),
    '#default_value' => t('Enter some text'),
    '#description' => t('Please use this field to submit some text'),
    '#required' => TRUE,
  );
  return $form;
}

creats a form with:

• A single textfield element
• Accessible XHTML with form labels
• Potentially localized labels, translated into any number of languages
• A bit of similarly localized help text below the element
• Validation of the form submission, with the field content marked as required

That's a separate item of form functionality for each array key. And as long as you use Form API, Drupal handles validation and input sanitization for you, thus massively reducing the risk of attack by SQL injection or XSS.

Bookmarkable search URLs with POSTed search terms

But there's a catch. To encourage best practice in terms of form submission and friendly URLs, Form API defaults to HTTP POST. If site searching used Form API (which it does) then what impact would that have? Successful searches could never be bookmarked, because the URL on its own doesn't capture the POST submission.

The search module tackles this by adding an extra twist to Form API. At the end of submission processing are the following two actions:

• Call either the function named in $form['#submit'] or $ID_submit, where $ID is typically the name of the original form creation function ("myform_some_form" above)
• Finally, either return to the original action page of the form, or redirect to any URL specified in $form['redirect']

The search module therefore uses a function called search_form_submit to grab the POSTed search terms, and redirect the user to search/$SEARCH_TYPE/$SEARCH_TERMS. $SEARCH_TYPE is "node" for Drupal's out-of-box textual node searching, but if you install some other search module e.g. Apache Solr then it'll be e.g. "apachesolr_search" instead. Result: bookmarkable search URLs.

Writing your own module to handle searches

This has important ramifications if you're trying to piggyback off core search somehow: if, say, you're still using core search or a third-party module for the actual result-finding, but then you want a page other than core search to display the results.

If you want the main site search form to redirect to your own pages, for example, then you have to (a) add your own $form['#submit'] function to the stack and then (b) use that to change the core search's $form['redirect']:

// Implementation of hook_form_alter(), adding an extra submit callback to
// search forms identified by their existing callback
function mysearch_form_alter(&$form, $form_state, $form_id) {
  $submits = array(
    'box' => 'search_box_form_submit',
    'form' => 'search_form_submit',
  );
  if (is_array($form['#submit'])) {
    $which = array_intersect($submits, $form['#submit']);
    $which && ($form['#submit'][] = 'mysearch_form_mysubmit');
  }
}
// Submit callback, which changes the redirect using a regular-expression replace
function mysearch_form_mysubmit(&$form, $form_state) {
  $form_state['redirect'] = preg_replace('/^search\/[^\/]+/', 'search/my_special_search',
    $form_state['redirect']);
}

Now you've got all your site search forms redirecting to a bookmarkable page at search/my_special_search/$SEARCH_TERMS. All you have to do now is write a menu callback for that page: from here on in you're on your own for now.

The UK government’s Central Office of Information (COI) has produced a draft report on governmental departments' adherence to browser standards and asked for feedback. Depressingly, the report is not available in a web friendly format even though there's no real reason for it to be only released as Word and PDF.

You can read a breakdown of the worst bits on The Web Standards Project, but here's the feedback I just emailed webguidelines@coi.gsi.gov.uk:

Hi,

I appreciate the COI's desire to provide roadmaps for cross-browser support, but I'm otherwise dismayed at the recent publication's back-to-front emphasis regarding browser standards support. It feels like the publication has been put together by people who are remote from the current thinking on web standards and how best to both promote them and take advantage of them.

As a web developer I've had a reasonable amount of experience in developing sites cross-browser, and generally the quickest and cheapest site creation (and the least patronising or inconveniencing to the eventual end users) is effected by developing first on the most standards-compliant browser available, regardless of its user base. Then, once the site is stable and well-built according to the standards (which are there for reasons other than semantic fussiness), one can use *freely* *available* frameworks to compensate for browsers which do not follow the standards (which may be more popular). It involves more effort at the start in exchange for a much smoother site construction later on.

Let me repeat that: building sites according to web standards, then accommodating bad browser behaviour, is CHEAPER, QUICKER and MORE ROBUST than what you implicitly propose i.e. building with bad-but-popular browsers in mind, and then looking at shoe-horning in browser-specific fixes for the others.

If you inconvenience the users of good browsers because there aren't many of them, you are taking us back to the bad old days of 1990s browsing. I haven't seen the phrase "We advise you to upgrade your browser version" (which I take verbatim from p4 of your report) on any site I respect and trust for almost ten years. Ask any decent web developer: it's no longer necessary, and frankly it reveals far more about the mindset of the site designers than about the state of web technology.

Like the proposal's guidelines, its consultation is happening the wrong way round, and highlights a top-down mentality behind composing such documents. Sharp, savvy developers recruited from any of the vibrant UK web conferences---dConstruct, OpenTech, Barcamps---would have been glad to have helped the COI out before this fundamental missing of the point was published, were they to have been asked. It would certainly have saved both COI and the web community at large a lot of heat, friction and wasted effort.

Yours faithfully,

J-P Stacey

PS: I was originally going to send this via your website's feedback form. After having read your proposals for building good sites I decided to email it instead, just in case.

You've got a month to comment yourself, if you're a UK or European developer. Feel free to use the above template, only I'd recommend changing the name at the bottom.

Web architects must understand that resources are just consistent mappings from an identifier to some set of views on server-side state. If one view doesn’t suit your needs, then feel free to create a different resource that provides a better view (for any definition of “better”). These views need not have anything to do with how the information is stored on the server, or even what kind of state it ultimately reflects. It just needs to be understandable (and actionable) by the recipient.

--- Roy Fielding on creating new resources for REST architectures.

In Javascript, trailing commas are to be considered harmful. Strictly speaking, they're not allowed by the syntax, but this wouldn't be such a problem were it not for the fact that some browsers (including Firefox) will quietly ignore them, pretending briefly that Javascript's syntax is Pythonic or, um, Rubric. The safest route to take is to avoid trailing commas wherever possible. I've mentioned the general problem before, and the hard core among you would probably go so far as to change their formatting to highlight trailing commas.

But what makes it all far, far worse is that IE6 and IE7 can sometimes produce error messages which, as is usual for those browsers, contain no useful information whatsoever.

Here's a recent example:

Line: 64432871
Char: 2
Error: Expected identifier, string or number

See that impossibly high line number? That's a result of the parser being struck soundly on the head by the syntax error, and consequently dribbling its way past the end of the Javascript file. IE's incomprehensible "English" error message conspires with circumstance to make the whole report of no help at all.

Something like JSLint, on the other hand, is of tremendous help, and we'll be running as much Javascript through it as possible in future. JSLint is just as unforgiving, but as it's reliably unforgiving and incredibly communicative with it then that's a bonus rather than a detriment.

It's sometimes a little too strict to be useful, complaining about implicit global variables (even when that variable is called window). My suggestion is to ignore those reports, though; but watch those commas!

Lurking in a dry, legalistic and apparently quite specific page on the Drupal website, is the commendable result of a lot of hard work, both from the the Software Freedom Law Center and from the Drupal community.

Drupal.org have produced a Licensing FAQ to explain some of the subtler aspects of licensing under the GPL. The questions themselves are Drupal-oriented, but the FAQ itself has been prepared by the SFLC, an independent body, so the answers are broader than that.

I've noticed from the slightly confused sidelines that Drupalers have been niggling away at these issues for ages. Their heated exchanges and occasional quarrels are the fuel that has kept this wagon moving, and they've finally rolled it into town with a GPL-in-practice primer that's worth reading, whatever you're working on, and especially if you're integrating with web services or third-party libraries. Well done to all involved.