⇥ Goodbye from T·A·B

This is my last post on this blog. I have enjoyed having a place where I could write my thoughts more or less as they formed in my mind, and it seems that a fair number of people enjoyed reading what I had to say.

But times change. I own a company that deals almost exclusively with PHP knowledge, and it seems absurd that I should write about PHP here while php|a almost never gets to publish my pieces.

By the same token, various pieces that I write on Mac and on computing in general often make their way to a number of other publications, where they reach a broader audience and undergo the professional scrutiny that, for obvious reasons, cannot be part of a personal blog’s editorial process.

More than anything else, however, I’ve decided that I want to do fewer, but more meaningful, things with my life. In the past year or so, this blog has often had to take a backseat while other activities demanded, and usually received, my attention. I’m not a big fan of doing things halfway, so, instead of allowing it to sputter along with the occasional post, I’m going to let it fade gracefully into the twilight.

This Website will remain up, but from this point on only as an archive of words that I have written, and as a bibliography of words that I will write elsewhere.

If you have ever visited T·A·B, thank you. If you’ve ever found something here useful, you’re welcome.

⇥ You are not “Mr. X”

I keep coming across code like this (lifted, verbatim, from an OSS project I’ve been working with recently):

$a = $num * $coeff + $_SANITIZED_GET['val'];

What, in the name of all that is good and just, is “a?” Or, for that matter, what are “num” and “coeff?”

Computer manufacturers, OS vendors, and programming tool developers have worked for decades to give us the ability to create identifiers of arbitrary length. Personally, I’d much rather see someReallyLongNameThatLooksALittleRidiculous than a function or variable name that won’t tell me what it does at first sight.

The same goes for data. A “1” and “0” in a database don’t tell you as much as “Yes” or “No,” which are just as localizable, indexable, and searchable. Enumerations, as far as I’m concerned, should be verbose unless there are very compelling space or performance requirements that say otherwise.

I know that there are many people who disagree with this approach, but their arguments tend to fall in the “that’s the way I’ve been taught to do it” camp. The reality is, a numeric enumeration is just as arbitrary as a string-based one, but much harder for the human eye to make sense of—and we all know that, sooner or later, all data is looked at by a human eye. There are some circumstances in which performance and space constraints come into play, but otherwise the development tools at our disposal are mature enough to handle either type as easily as the other.

Besides, using numbers to identify non-numeric value is a domain violation. It used to be a necessity twenty years ago, but the vast majority of us work in environment that are well past that point. You wouldn’t want to be called “492829,” right¹?

So, if you are writing a book or teaching a course on programming, please teach your readers and students to write descriptive code. They’ll be better for it, and we’ll be grateful that you did.

⇥ Generations sideways

Matthew Baxter-Reynolds on the various toolsets available to mobile developers:

The fact is that if your day job involves sitting in Visual Studio writing C# applications, or building Java applications in Eclipse (which will be most of you – albeit not necessarily in Eclipse), when you fire up Apple’s Xcode and start building CocoaTouch applications in Objective-C you’re going to come face-to-face with a toolset that has not had the sort of love put into it that the open source community has put into the Java toolset and associate platforms, or that Microsoft has put into VS and .NET over the past 10 years. Apple has been caught on the back foot by the popularity of its tools and is at least one, if not two, generations behind. For example, the iOS version of Objective-C does not have garbage collection.

Leaving aside the mistake at the end (which Baxter-Reynolds corrects at the bottom of the article), I’d say that Apple’s approach to its toolset is simply different, in some cases for the better, and in some for the worse.

Cocoa seems to be built on a simple premise: that developers know how to develop, but don’t know how to design interfaces; which, I am sorry to say, is probably not far off the mark.

Thus, Apple’s assumption is that developers don’t need fifteen ways to parse an XML file, because they already share enough common knowledge to do it on their own—and if they don’t, chances are that they will be smart enough to come up with their own solution and share it with the world.

The focus of Xcode is, instead, on creating an environment where even a person who is not well versed in user-experience design can still write an app that looks and feels good. Therefore, a lot of emphasis goes into good interface metrics, good look and feel, and so on.

In other words, Apple is counting on engineers commoditizing the aspects of software development with which they are most familiar, and focuses instead on filling the gaps in other disciplines that, traditionally, trip them up.

Case in point, Objective-C has lacked a public JSON framework for a really long time¹. By all accounts, this should have made OS X and iOS very unsuccessful platforms for Web service-enabled apps; instead, developers simply built (and collaborated on) several JSON frameworks of their own. On the other hand, both of Apple’s operating systems present their users with an environment in which apps use a consistent design vocabulary that is well within the grasp of even the hard-core Luddite.

There are two reasons why this is important. The first is that a lot of development is still done without the benefit of a designer’s expertise. Even medium-size teams that build apps for large audiences place much more focus on engineering than on usability and ergonomics; thus, a toolset that promotes basic design principles can be beneficial from the get-go.

Second, even where designers are involved, developers are still responsible for implementing the code that makes design possible. Therefore, a development platform that emphasizes design creates a more collaborative environment for all involved.

That said, there are some aspects in which Apple’s toolset has dragged behind its competitors. Memory management, for example, has long been one, but Apple’s approach to solving the problem of managed memory has been a very deliberate one: they tried garbage collection, figured out that it didn’t quite work (particularly on iOS, where resources are relatively scarce), and moved to a different solution (ARC) that somehow manages to create a managed-memory environment with less overhead than its unmanaged predecessor.

All in all, my personal experience has been that every development environment has its flaws and benefits. Even Xcode’s focus on design doesn’t prevent the creation of plenty of really horrible apps. Still, that’s a far cry from saying that it’s generations behind—I’d rather say it’s generations sideways.

(Via Daring Fireball).

⇥ Right conclusion, wrong reasons

ORM is an anti-pattern:

The reason I call ORM an anti-pattern is because it matches the two criteria the author of AntiPatterns used to distinguish anti-patterns from mere bad habits, specifically:

1. It initially appears to be beneficial, but in the long term has more bad consequences than good ones

2. An alternative solution exists that is proven and repeatable

It is the first characteristic that has led to ORM’s maddening (to me) popularity: it seems like a good idea at first, and by the time the problems become apparent, it’s too late to switch away.

I agree that ORMs are, in general, to be treated with much suspicion. Their main shortcoming is that they are a square-peg solution for a round-hole problem: attempting to map a data model to another inevitably leads to conflicts and issues, or there wouldn’t be a need for the two different data models in the first place.

The real problem with this blog post, however, is that it uses an incomplete definition of anti-pattern (there’s Wikipedia for you). In his original article on anti-patterns, Andrew Koenig¹ speaks specifically of anti-patterns as juxtaposing to patterns; like ying and yang, you can’t have anti-patterns without having patterns that they can be related to.

The significance of this is that an anti-pattern is not just something that is “bad on its own.” More often than not, it is more like “a pattern that has gone bad”—the right concept being applied under the wrong circumstances.

Thus, ORMs are not inherently bad. They are just inappropriate for a number of settings in which they are, admittedly, used. An ORM can be an excellent solution to scenarios in which a key-value store is not available, or in which a very simple schema is all you need. In those cases, the overhead of an ORM may be an acceptable tradeoff for the simplicity that it brings to an application.

This, in turn, brings me to another point: using an ORM does not excuse you from understanding the underlying data model and the way the ORM uses it. If you do, the ORM becomes almost inevitably an anti-pattern, because you’re resorting to magic and applying a solution without knowing the problem.

Thus, while it’s true that ORMs encourage (and mostly fail) the developer not to think in terms of SQL queries, there is no way to use an ORM well without understanding relational data mapping. Or, put another way, the ORM doesn’t replace your knowledge of SQL—it simply adds one more layer of indirection to it.

An argument could be made that ORMs do not scale well over time, because the relationship between the overhead they introduce and the complexity of the underlying data model is not linear. This, however, seems to me like a symptom of application design, rather than an inherent flaw in ORMs.

Let me give you an example; if you’re writing an application that you know you will only need to run once (for example, some sort of importer or data analysis function), an ORM can greatly simplify your job and bring immense benefits. Will you care if it doesn’t scale? No, because you’re writing a single-use application.

If, on the other hand, you’re writing a more complex application, then you need to evaluate how well an ORM will hold up over time. That’s as much an art as it is a science, but it doesn’t make ORMs inherently bad; it simply means that you need to learn to design software properly.

⇥ Dashes, spaces, and incompetence

Take, if you would, a look at your credit card. Unless you come from a different planet, chances are that it, like mine, has a series of digits separated by spaces. Depending on which kind of card you’re looking at, these numbers may be grouped in different ways, but, generally speaking, this is probably a valid statement for every kind of credit card in existence.

Those spaces are there for a very specific purpose: they break the visual flow of your credit card number, providing your brain with anchors that it can use to group the digits together in a way that makes them easy to process. Although the number as a whole is no easier to remember, it’s much simpler to copy and compare something like “123 457 789″ than “123457789.”

Why, then, do so many developers still insist on asking users to enter their credit card numbers “without dashes or spaces?”

The problem here is not just one of developer laziness. Sure—in the specific example of credit card numbers, all that needs to be done at the code level can be expressed with a regular expression that borders on the stupid:

$creditCardNumber = preg_replace('/\D/', '', $originalCardNumber);

In some other cases, building good heuristics that are flexible enough while providing the proper constraints can be a little trickier, but the real issue is that so many programmers don’t even try. And that, unless you’re writing your applications in assembler, is simply incompetence.

Learned helplessness

There is a beautiful concept in cognitive psychology called learned helplessness. The basic idea behind it is that people who repeatedly fail at a task will eventually blame themselves for the failure and give up trying to do it.

This, in a nutshell, describes perfectly the way I see most non-technical folk relate to computers. They’ve just been hit so many times by software that makes no sense to them that they approach every task with fear and uncertainty—instead of making users more productive (and, therefore, happier), software makes them more depressed.

Why does this happen? Because of a million little (and big) things like the credit card snafu. Every time the user encounters a scenario in which an application creates a disconnect between reality (spaces on my credit card) and its software representation (no spaces or dashes!), the sense of helplessness increases, and productivity decreases as a result.

Let me fix this for you

The good news is, this kind of problem is due entirely to developer incompetence, which makes it easy to fix—after all, there are far fewer of us than there are users, so education should be a far simpler task.

In the specific example of credit cards, the issue is usually related to the fact that the upstream credit card provider requires that numbers be passed to them without any extraneous character, and we simply transfer that constraint up to our downstream user.

However, the constraint is not transitive: it makes sense in one direction because the provider has created an interface built for engineers, who (at least in principle) should be able to deal with the resulting requirements. Our users possess no such ability, and expect an interface built for them.

From a more general perspective, solving this kind of problem is not that difficult: you simply need to look at the constraints you create from the user’s point of view. Credit cards numbers have spaces in them in real life, and that’s how users will want to input them. There. Simple as pie.

This doesn’t mean, however. that you need to take this too far in the other direction and create skeuomorphs that attempt to reproduce reality too closely. For example, making your credit card input form look like a credit card is dangerous because the various types of credit cards are different enough that it could create confusion instead of dispelling it. Besides, the user is probably capable of abstracting the underlying data model enough that such a skeuomorph would feel patronizing.

And, please, do not think that this is something that only designers should worry about. Developers are meant to solve problems, not churn out bytes. If you don’t want to be treated like a code monkey, stop acting like one.

⇥ Suggestions for a younger developer

Every now and then, I get asked by developers who are just getting started in the trade if I have any suggestions to help them out—favourite language, tips and tricks, and the like.

None of these things matter, really, but there are a few things I wish I had known when I started out that have nothing to do with the mechanics of software development.

1. Be humble

You just finished college with full marks. You know hundreds of algorithms backwards. You’ve read Don Knuth’s seminal programming series cover-to-cover (something that Professor Knuth himself would probably be disinclined to believe).

Alas, that does not a programmer make you. You’ll find out soon enough that being successful at writing software means quickly discarding options that are unlikely to lead nowhere, while zeroing in on those that will. And, more often than not, it means throwing away the book and violating every rule to get where you need to go.

2. There is no magic

Never assume that other developers are necessarily smarter than you. Remember that the people who write the tools you use have access to the same kinds of resources and techniques as you do.

Never accept the frameworks and APIs at your disposal as black boxes; understanding how they work internally will help you write better code against them.

3. Programming is a craft, not an art

Good code, like art, is many things to many people. Working code, however, is undisputedly code that performs its tasks properly and efficiently.

A good developer is like a good artisan, constantly balancing the needs of form and function, but always focused on making things work in the most practical way possible.

4. Software solves problem

Writing code is a crucial, but relatively minor, part of the software development process. You write code to solve problems, and can’t be good at one without being good at the other.

Strive to be part of the entire process that leads to the development of a system; insist on being treated not as a code monkey, but as an integral part of the overall team that contributes more than mere lines of code.

5. Code doesn’t leave sawdust

One of the best aspects of software development is the fact that it is a purely intellectual exercise. With a modicum of precaution, we can experiment knowing that our only waste is time; there is no wood to chop, pencils to sharpen, chemicals to react, or paper to crumple.

Sometimes, trying things out in practice leads to unexpectedly efficient solutions that all the planning in the world could not have anticipated. And, when it doesn’t, there’s always source control to take you back in time, ready for another try.

⇥ The easiest way to add unit tests to your application

Unit testing shouldn’t be hard. In fact, given its usefulness, it should be easy and pleasant—a tool that every developer would never want to do without.

And yet, I see programmers (and, more frighteningly, systems architects) struggling with it constantly. In many cases, they are saddled with large codebases that have never seen any tests whatsoever on one hand, and the fact that a recent changes has caused their entire system to crap out on the other.

The unfortunate thing is that most “experts” will tell you that you need to drop everything you’re doing right now and spend however long it takes to build a complete testing harness for your project.

These people, in my oh-so-humble opinion, live in a fairy-tale land in which deadlines are things that happen to other people and management is made entirely of sugar cookies.

Back in the real world, stopping development for weeks while you figure out how to add unit tests to cover your entire codebase is simply something that cannot be done (at least, not if you want to keep your job), no matter what future benefits it might bring.

The good news is, adding unit testing to your existing project only takes five minutes—which is pretty much how long it takes to get a unit testing framework installed. That’s it. Move on.

A test today is better than a thousand tests tomorrow

Still here? OK, read on.

Chances are that your application “mostly works” today. If it didn’t, you’d have much bigger problems to worry about than unit tests. Adding unit tests is not going to solve any problem because you don’t have any.

That’s fine; you just need to look at testing in a different light.

Where unit testing helps is in managing change. The job of unit testing is not to determine that your application works as advertised: that’s what your QA process—of which unit testing is part—is for.

Rather, unit testing is there to help you ensure that changes you introduce in your code do not have consequences that you did not intend.

Once you make this decision, adding unit tests becomes really easy—and very productive.

Fixing bugs

A typical example is correcting a deficiency in your code. Obviously, you can’t fix a bug until you’ve reproduced it. And, when you have figured out a way to consistently trigger the bug, you’ll have to do so multiple times as you try to figure out a solution to the underlying problem.

Curiously, that exactly one of the things that a unit test does well. Instead of triggering the bug manually, you can simply write a test that does so programmatically; in so doing, not only have you added a very important test to your code—you actually made reproducing the bug (something that you will probably need to do multiple times as you fix it) much easier.

Refactoring

Another place where writing unit tests is an easy part of the development process is refactoring existing code. The worst thing that can happen here is that a change you make breaks something else, and you don’t find that out until the code is in production. That, as they say, would be bad.

Since that’s something you (a) want to avoid and, therefore, (b) you will have to track anyway, writing a unit test is a great way to automate the process. More interestingly, it’s an easy way to write a meaningful test that validates how your application works as opposed to what your code does (more about that later).

Adding new functionality

This leaves with the scenario in which you’re writing completely new code¹.

Proponents of TDD and (to a certain extend) AOP will tell you that you should either write your tests before your code, or alongside it.

I know I will probably catch a lot of flak for this, but here’s my recommendation: do absolutely nothing.

Writing code is often a process of near-scientific discovery. The abject failure of the waterfall model should have taught us by now that the idea development and architecture are two completely separate phases is simply at odds with reality.

In the real world, we have to contend with imperfect specifications, unknown constraints, and the distinct possibility that, halfway through the development process, we find out out that we’re trying to solve the wrong problem.

As a result, I, personally, prefer to write code in an almost free-flowing manner, focusing on finding the best solution to the problem at hand. Throwing testing in the mix, while definitely a good idea in principle, just adds one more level of complexity to an already overly complex task in practice.

This doesn’t mean, however, that tests are out of the picture.

If you think of unit tests as a tool to manage change, in this particular scenario their job is to ensure that the change you’ve made (adding new code) works the way you mean it to. In other words, once your code is completed and working the way you think it should, you can write a test that exercises it to “solidify” it as a future constraint.

The best time to do so is when you commit your code to HEAD². That’s because committing to head indicates specifically that the code is complete and its behaviour should therefore be invariant from that point forward.

Better yet, if you work in a team with more than one person, you can simply make writing tests part of the code review process—when you push your branch for review, whoever reviews it also write the tests. In addition to spreading the workload, this ensures that another person validates the principles under which you built the software, increasing the likelihood that they will poke holes in your programming and reduce the incidence of defects.

Writing meaningful tests

Writing tests is pointless if they don’t actually help you manage change. The question, then, is: how do you write meaningful tests?

That’s a complex topic, but the best thing you can do is to think of unit tests in relation to software design. (Or, you can grab the slides from last year’s Codeworks Tour, where my colleague Keith Casey made a wonderful presentation on this topic.)

In architectural terms, software is a kind of mapping between visible affordances (what your application can and must do) and constraints (the ways in which it must be limited so that things are done properly). Any kind of QA that you perform on your software (including unit testing) must be built around the concept of validating your code as a whole, even when you are only exercising a small portion thereof.

A good test, therefore, is not concerned with replicating all the possible sets of inputs and output of a particular piece of code; it’s only concerned with replicating those sets of inputs and outputs that can happen during its intended usage.

The difference is critical, because in the first case you’re exercising the code in isolation from its surroundings, while in the second you’re exercising it based on the role it’s meant to play in the final product.

Of course, this still means that you need to test all the realistic inputs—including edge cases and input that is purposely incorrect or malicious in nature. And that’s why it’s often better to have another person write your tests, since they will be able to look at your code in a more detached way.

What about code coverage?

It should be obvious by now that complete code coverage is not a useful goal of unit testing. Instead, it should be a consequence of a good testing strategy.

Again, the difference is substantial. If you’re trying to achieve code coverage for the sake of it, anything less than 100 percent means that you need to write more tests.

If, on the other hand, 100 percent should be the consequence of a good testing strategy, situations where it is not achieved could simply indicate that you’ve got dead code branches that need to be pruned. Writing more tests then becomes the next step in the process.

Testing is a continuous process

All these things will help you get started with unit testing, but writing good, meaningful tests remains a hard thing to do.

This doesn’t mean that you should be discouraged, or that you should give up. Just think about testing as a process of continuous improvement. An imperfect test is better than no test at all—as long as you understand the limitations of your testing strategy and strive to make it better over time.

Some offbeat reading

You’ll find articles and books on how to write good unit tests all over the place. Most of them are bad, many are well-intentioned, and very few actually explain why you should write unit tests in a particular way.

Rather than give you yet another list of those, allow me to suggest three books that are not on unit tests at all, but, instead, on the psychology of design, which is, in turn, a great tool to help you understand how to write tests that are meaningful.

• The Design of Design is a great read from Frederick Brooks (suggested to me by Joël Perras) on the process of designing software.

• The Design of Everyday Things by Donald Norman (one half of Nielsen Norman) is an excellent exposition on the psychology behind design.

Both these books should help you understand what to test for in relation to how a software application works. Rather than focusing on the mechanics of your code, building tests around its intended functional specs will yield much better results (and help your sanity).

Finally, you may want to read Apollo by Charles Murray and Catherine Bly Cox. This book has little in the way of technical content, but shows how the Apollo program was almost destroyed by an insistence on disconnecting testing from development, until George Mueller told engineers to suck it up and test the whole thing as one unit.

⇥ Is PHP running out of itches to scratch?

Over on his blog, my partner Cal has been wondering aloud whether Drupal should simply fork PHP, or get rid of it altogether. I hesitate to add anything to the discussion because I don’t want it to look like we’re feeding troll material to each other, but he does raise some interesting points.

I think it’s fair to say that the pace at which PHP core is being developed has slowed down considerably over the past couple of years, while the development of many projects based on it, like programming and application frameworks, has sped up and continues to grow at a fast pace.

But this doesn’t mean that we’re running out of steam. The PHP ecosystem is simply refocusing outside of core, where it has a lot more freedom of action.

This is primarily a consequence of two items. The first is the fact that PHP core has no strong leadership that can take the base language in a specific direction.

This has always been a primary design feature of the project—one, I may add, that has produced some great results. Without anyone to force PHP in a specific direction, the language has evolved haphazardly but comprehensively, which is what makes it so appealing to so many.

However, the decision was made some time ago to close the door on building new libraries into core and instead shift them to PECL. This was probably the right decision (who wants a bloated and increasingly difficult to audit core?), but it was implemented without considering the fact that the average PHP user has neither the knowledge or inclination to understand how to install and run external libraries that they can’t download in PHP form and include in their scripts.

This is crucial, because PECL and PEAR are, despite the valiant efforts of many brilliant developers, a complete mess. Obscure to work with, poorly supported, and unduly complex, they are simply irrelevant to the vast majority of PHPers.

This, in turn, affects downstream application developers, who, faced with a client base who can’t deal with PECL and PEAR, simply opt for building their own plugin architectures—and, to be frank, often do a pretty good job of it.

The risk facing us, as I see it, is not that Drupal, or WordPress, or whoever may decide to fork PHP or abandon it altogether. Rather, the problem is that there is no real way for these projects to provide upstream positive feedback to PHP core.

As I pointed out that the meeting that Cal references (I was the instigator of the discussion), core developers can’t improve PHP if they don’t know what needs improving, and downstream developers are forced to resort to needlessly duplicate functionality that they could instead feed into and pull out of core. This, in turn, would enable the latter to focus on what really makes their projects unique and make the whole PHP ecosystem better in the process.

⇥ On writing (better)

Over the last umpteen years, I have come to the conclusion that the vast majority of people (and techies in particular) have three main fears:

• Speaking
• Writing
• Picking up the phone

In the past, I have talked about all three activities, but two recent events conspired to make me write this post. The first was an opportunity to co-write an article with my friend and collaborator Lex Friedman. The piece ended being killed for reasons beyond anyone’s control, but the process of actually sitting down with someone and writing in the same document at the same time brought into sharp relief the fact that many others who write for a living use an approach to putting thoughts to paper that is very similar to mine.

What pushed me over the edge, however, was the fact my son was assigned a paper on black history, which he has been enthusiastically working on for the last week or so. Being only seven, however, means that writing doesn’t yet come natural to him—just like, I’ve realized, it doesn’t come natural to a lot of other people.

Part of the problem is that schools don’t seem to teach proper composition¹. Curricula are obsessed with the rules of grammar and the history of literature; the former is undoubtedly important and useful (which I’m not so sure could be said about the latter), but is secondary to being able to express your thoughts and ideas properly—which is the real goal of writing.

Writing as a process

Let’s start by abandoning the term “writing” and replace it with the term “composing.” The sound of a pen scrawling or of fingers typing is but a relatively small and unimportant part of a much larger process that, in one way or another, takes place in the mind of everyone who writes for a living. Yet, the first thing that so many do when assigned a writing process is to open their word processor or notepad and start composing.

Instead, the first activity that the seasoned writer does once assigned a writing project is… something else. I usually entertain myself with something completely unrelated while my brain processes and sorts out information and organizes my thoughts. I know of writers who go have a drink (usually by themselves—writing is a very lonely job), take a walk, make phone calls, play with their children… anything but actually sitting down and writing.

You see, before you can write, you need to figure out what you want to write. Many writing courses suggest that anything on paper is better than nothing, but I disagree. Putting words together is a complex process that requires a lot of brainpower—brainpower that cannot otherwise be used to make sure what you want to say makes any sense. It’s much better to get things organized first, and this could well be a process that takes the form of you writing down an idea or two, particularly for longer projects—and then worry about the letter side of things.

In general, I find that the complexity of this set-up process is proportional to what you have to write. For an e-mail, it might take a few seconds of thought; a newspiece might require fifteen minutes or so, and an opinion piece—well, let’s just say those are hard, which is probably why so many of the ones you find are so bad. For books, the process can go on for days or weeks.

The goal of this initial process is, essentially, to design your story. You need to decide what your conclusion is going to be, and work your way backwards to make sure that everything you want to say fits cohesively together. I don’t mind telling you that I have, more than once, started composing a piece convinced that I wanted to make a particular point, only to find out that a logical train of thought led me to a completely different conclusion. Good luck figuring that out while you’re trying to find the right words to use, worrying about syntax and orthography, and typing all at the same time.

Telling a story

When you finally do decide that you’ve thought things through and you know exactly what you want to write and what conclusions you want to reach, you can start writing. Here, there are two mistakes that I see people make; the first is that they write sentences but do not tell a story.

Every single piece you write is an adventure, with a beginning, a development, and an end. It doesn’t matter whether you are composing an e-mail to your clients or writing the next Great American Novel—you still need to take the reader by the hand and walk with them through every nook and cranny of your story. Your writing needs to be engaging, or you will never move beyond your grade-school reports.

Alas, most people write in short, halting sentences—I’m not sure if that’s because they were taught this way at school, or if it’s just a clever ploy to avoid having to properly punctuate. To a reader, that’s like driving down a flat, featureless highway in the passenger seat of a car whose mad driver constantly accelerates to maximum speed and then stomps on the brake pedal: it’s not just boring, it’s nauseating. When you read, years of habit have trained your brain to give a certain weight to the punctuation you encounter on a page; abusing it is like continuously punching the reader’s mind with brass knuckles.

Despite its small size, the period is an important signal for your mind: it tells Mr. Brain that it needs to stop reading and spend some time absorbing what it has just seen; therefore, short sentences have a jarring effect on the flow of a story and soon tire the reader. The same, of course, is true of long, winding, rambling sentences with no end.

The second problem that most people seem to have is that they think that writing is about words. It isn’t. Writing is, first and foremost, about communicating. When you write a story, the first goal should be to explain clearly and properly whatever it is that you want to say.

Remember, the focus now is on writing—getting things on paper. Don’t waste your time thinking about whether each sentence flows properly, or whether there are dissonances or repetitions in your text—and please, for the love of everything that is Good and Just, throw away that thesaurus. It’s a waste of time, and the word alternates you’ve found are, most likely, the wrong ones anyway.

To be clear, “avoiding short sentences” doesn’t mean that you must throw words at the problem; don’t use five words when three will do. You may be getting paid by the word, but your editor is not daft. He knows when you’re padding, and he knows that padding adds nothing to the meat of a story. Even if you just write for your blog, be concise and clear. It makes everyone’s life easier.

Clean up

Now that you’ve got things on paper, so to speak, it’s time to clean them up. Go over the stream-of-consciousness text that came out of your mind during the first draft, and fix anything that’s out of place. This is where you pay attention to flow, consistency, coherence and linguistic considerations like repetitions and punctuation.

The clean-up phase is both critical and amazingly boring. Getting an idea on paper is hard work and, by the time you’re done with the first draft, you’ll want to just move on to something more fun, like, say, getting sloshed or overdosing on sesame pretzels. Alas, making sure that your text doesn’t sound like it was vomited by a five-year-old is very important—trust me when I tell you that the only thing more humiliating than seeing your story being mutilated by an editor is recognizing that the editor has done a better job with it than you did.

Therefore, it pays to spend a little time making sure that your text is as good as possible. Think of it as optimizing a piece of code—something you’re supposed to do only once you know the code works and you’ve identified its weak spots.

Tricks of the trade

There are four essential tools that every author needs to master; they are called comma, semicolon, colon and period.

Am I being funny? Not at all, because the vast majority of people has absolutely no idea how to use any of them individually—let alone all together.

Punctuation is the single most important aspect of your writing; it helps resolve ambiguities and it provides a rhythm for the flow of your discourse. Maybe it’s the fact that I have an almost fetishistic attachment to proper punctuation, but I’m convinced that a good use of the gamut of marks available to you will make up for a lot of other mistakes. Some of the best articles I’ve ever seen come out of the php|architect pipeline have been written by authors who had, at best, a basic knowledge of English, but who could write engagingly and coherently by using all the tools at their disposal, transcending their language handicap with ease.

Remember that punctuation is not just a typesetting concern. It is a tool of incredible power that helps you mark the hills and valleys in your story; in a way, it is to writing what proper inflection and timing is to speaking: get it wrong, and readers will not understand what you’re saying (or, worse, misunderstand it). If you have to choose between good grammar and good punctuation, focus on the latter, because editors can fix your grammar, but bad punctuation will actually skew the meaning of your work.

You might be wondering why I haven’t talked about style. The reason is simple: style is always unique. You can try and imitate someone else’s, but you will always end up subtly modifying it to make it your own—it’s just inevitable. The only way you form a style is by reading—as much as possible and from as many different sources as you can—and by writing until you’re comfortable with whatever experience your text projects.

Dealing with feedback

Writing even the simplest of things is an exercising in baring your soul. Especially when you’re writing anything other than a factual report, you’re basically showing your readers the colours of your ideas and personality—and giving them carte blanche to judge and critique them.

And they will. Everybody who ever reads your text, from your editors to your blog’s readers, will pass judgment on your ideas and, by reflection, on you as a person. Whether it’s a note from your ed telling you that you’ve messed everything up and he had to rewrite half your article, or a comment on your blog, feedback is often hard to take.

It is, however, also an important tool for learning to do a better job, which makes being able to tell the good apart from the rest very important. If you’re fortunate enough to work with a good editor, he or she can be a veritable treasure trove of learning opportunities. My editors at Macworld and our own editorial team—both subject to incessant drivel from yours truly—give me important pointers on learning to write better every time they lay hand on one of my stories².

Good feedback, like the gooey, chocolatey filling of a French pastry, is in the middle. You’ve got to let go of the haters—people who criticize instead of critiquing. Nothing can be learned from these leeches on the goodwill of a society that allows them to access the Internet, when they should instead be relegated to a dungeon and left to fend against wild beasts on a 24/7 basis. These are the folks who judge and comment based not on what you have to say or the logic behind your reasoning, but on the exterior appearance of your writing. They’re the kind of people who get up in the middle of Schindler’s List and jeer because Liam Neeson has a piece of lettuce stuck in his teeth. Even though they like to cover their stupidity with a veneer of cultural self-importance, they are absolutely meaningless.

By the same token, you’ve got to let go of the gushers. Knowing that people admire your work is great, and something to be always grateful for, but you can’t learn anything from people who think you’re already doing the best that can be done.

It’s those folks in the middle that you have to listen to. They will, usually politely (and sometimes tactfully), point out that they disagree with your conclusions and explain what they believe the flaws in your line of reasoning are.

Ultimately, your worst critic is likely to be yourself. In fifteen years of writing anything from e-mails to books, I can think of maybe two or three pieces I’m really proud of. Plus, of course, I’m acutely aware of the fact that, although I have spent nearly as much time in Canada as I have in Italy, I will never be as fluent or articulate as many of the people whose work I admire. Still, I’ve managed to stick around for a while without getting fired from any writing job for gross incompetence—and have no plans to make myself scarce any time soon.

[Update 2001/02/08: tightened up some language I wasn't happy with. I will not, however, change the expression “to come natural” with the more grammatically correct “to come naturally.” As far as I'm concerned, it's a perfectly acceptable colloquial expression—this is a blog post, not Anal Annie's Manual of English Obnoxiousness. To those who thought that was the only thing worth commenting on, thanks for making my point about feedback. Now go back to watching Schindler's List—you've done good³.]

Google and H.264 – Far From Hypocritical?

Simon Phipps, on the Google dropping H.264 from Chrome debacle:

But all these points are also true of Adobe Flash. So why not drop that too? Is it not hyprocritical to keep it? If you’re an absolutist, probably yes. But there’s a calculation going on here about steering the web into the level plains of truly open standards. H.264 support in the <video> tag is not the same as Flash support.

I do think, however, that his conclusion is incorrect in this particular instance. Google is not a disinterested party in the video format war; it controls the WebM codec de facto, because it originates the format and because several of the big-name members of the WebM consortium derive large portions of their income from it². It also controls YouTube, which is arguably the largest repository of videos on the Web.

Flash seems more like a red herring to me—the real question is, where are the disclosures? This action and the naïve reasoning that Google has presented gives no consideration to what a company whose motto is “do no evil” apparently stands to gain from this move, which could be something as simple as not wanting to worry about having to pay for royalties five or ten years down the road³.

What worries me and what I’d think should have worried Simon is the fact that this move reduces customer choice, which goes against the very principles of openness that Google claims to support. Given the current situation, under which they can continue to use H.264 without any significant cost, the appropriate choice would be to leave the codec in and let the market decide. If the open-source model yields a better result in the long run, as I believe it does, then there is nothing to fear.