Posts tagged ‘quality’

Great Big Crane now supports pip

This week, I started using Great Big Crane in real life to manage some of my buildout projects. I was surprised to discover how useful, slick, and bug-free it is. When we wrote it in a 48 hour sprint, I did not realize how functional and complete our final product turned out to be.

I filed about a dozen issues on the project as I used it, but surprisingly few of them were bugs; just feature requests and minor enhancements to make it more usable. I don’t think any of us were expecting to maintain this project when the contest was over. However, now that I see how useful it is, and because winning the dash has garnered a lot of interest in the project, I sat down for a few hours and added the one thing people have been requesting for it: pip support.

This new feature is fairly simple, and not fully tested, but the general idea is to be able to run virtualenv, manage your requirements.txt, and install the dependencies from inside greatbigcrane. This required a fairly invasive refactor of certain commands that we had implemented as buildout specific, but overall, it wasn’t a terribly difficult task.

What I have so far is certainly usable, but I suspect in the long run, it’s just a start!

Have a look at the sources here:

Why I don't like reverse and {% url %} in Django

Django has a feature that allows you to look up an url based on a function name and arguments. Here’s how it works:

urlpatterns = patterns('',
    (r'^projects/(?P\d+)/$', 'views.view_project'),
def view_project(request, project_id):
    # create the view
some_url = reverse("views.view_project", 4)
# some_url = /projects/4/
# sometemplate.html
<a href="{% url 'views.view_project' 4 %}">My project</a>

The idea behind is to separate urls, which are not supposed to change (because someone may have bookmarked them, there might be links to the page, etc) from implementation (, which can change at any time (due to refactoring, new features, and bugfixes). You can move functions around at will, and simply change to point at the right function without breaking people’s links. I love this decoupling.

The idea behind reverse and url is that you should not be hard-coding urls into your code, you should use the names of the functions being called instead. I’ve tried to do this because its the “proper thing to do” if you’re a django coder… but I don’t like it, and I’m going to quit using it in my personal projects.

Here’s why:
1) It’s harder to maintain. As stated above, I often change the name or location of a view function. When I do that, I have to go through all the files that have a url or reverse call and change the view there. If I had hardcoded the url, I’d only have to change it in I’ve been stung by this much more often than by changing urls.

2) Its harder to read. When you see “/path/to/something” you know you’re looking at an url. When you see reverse(‘some.module.path’, some, arg), it takes longer for the brain to parse, even if you know what the reverse call does.

3) In the case of {% url %} it exposes implementation details to the template author. Template authors should not know or care what python functions are being called internally. But they know what an url is, and what it represents.

In short, it adds an extra layer of abstraction to url handling. I like abstraction layers to be thin and useful; in the case of reverse(), the added complexity does not, in my minimalist opinion, justify the supposed gain in simplicity.

Offline Enabled Webapps And Open Source

I’m currently working on a rather simple Todo list application intended to meet the requirements I outlined earlier. I’m developing this as an offline-enabled webapp and while I haven’t gotten very far (don’t try it, it barely satisfies the most elemental requirements), I have some interesting observations to make:

First, the app is currently 100% Javascript. Its wrapped in a Django project because I’m going to have to make it online enabled at some point, but I wrote this app from the ground up to run in offline mode. This is a huge departure from traditional web 2.0 development (as of now, web 2.0 is to be considered ‘traditional’), where logic is mostly stored on the server and an ugly mess of ajax calls run that business logic on different events. Instead, I have a Javascript app that is surprisingly elegant. MVC under this architecture is basically SQLite (model), XHTML/CSS (view), and javascript (controller). Then I will have a workerpool to sync up with the server in the background.

As a result, the entire code-base for this app is being served to the web browser. So if you personally want to hack this app, you can download the source files from the browser. Basically, I can’t release this app as closed source. I could put a license on it forbidding you to modify or redistribute it, but you can still read the code; the source is open.

Of course, that’s not a problem for me, as I release most of my code as open source and its already up on github. But it could kill corporate migration toward offline-enabled web 3.0. Because while its one thing to keep your trade secrets locked up on the server and provide a few incoherent javascript calls that interact with that API, it is a completely different beast to put your entire app available for download as a .js file.

I suspect the open source movement has gained enough momentum that any companies who have these fears will simply be put out of business by more modern outfits that will spring up to take their place. Otherwise, either web 3.0 will fail to grab market share, or somebody will come up with a way to ‘compile’ javascript into a standards compliant byte-code so they can pretend nobody can reverse engineer their app. This would be a damn shame as its a politically-motivated technically useless layer of complexity on a web based architecture that I am finally happy to be working with.

Style As Communication

A couple weeks ago I read an article. I don’t remember the title, links, topic, or most of the content of the article; indeed, I likely should never have read it. I would have forgotten it altogether except one suggestion that you should ensure the signature on e-mails sent from your blackberry or iphone says “Sent from my blackberry/iphone”. In theory, this allows the recipient to know you were on a mobile when you sent the message and they can excuse the brevity and grammatical errors that tend to occur when typing a message on such devices.

When I receive a one-line comment followed by a second line stating ‘sent from my Blackberry’, my first thought is not, “Ah, they were mobile, they weren’t able to type a polite response”. To the contrary, I tend to think, “They couldn’t be bothered to go back to the office and send me a well-crafted reply. How can I trust they even thought about the question at hand?”

The thing is, how things are worded sends as much information as the words themselves. Critics of the Internet age have long pointed out that face-to-face communication is better because you can pick up on so many non-verbal cues in their gestures, posture, tone, and expression. Yet nobody realizes that text-based communication also says plenty about you and about the message you are conveying.

While we are instructed to ensure our cover letters and resumes have no grammatical errors because it makes a bad impression, in day-to-day business or interpersonal dealings, nobody worries over such things. We’ve all seen the despicable language that has evolved to support the character limits in Twitter and text messaging. It makes the most erudite communicators look like fools.

The full qwerty keyboard on my HTC dream is terrific, but I don’t get anywhere near the 100WPM I can get on my computer keyboard. Messages typed on the mobile can be painful to compose. I always put forth the effort to ensure my grammar is correct and the style is the way I want to sound. It takes me a while and I can’t supply that impressive immediate reply that mobile devices are famous for. But I can give you a hand-crafted response styled ‘just so’, to give you exactly the interpretation I wish you to receive. Chances are I won’t send the message until I get home and review it at a full keyboard where edits are easier.

One can argue that putting an emphasis on grammar and style is a waste of time and the world is clearly learning to evaluate only the content of messages. This is a shame. It restricts our ability to communicate. Properly wielded, style can say so much more than mere content ever will. Like pictures, style can be worth a thousand words. Instead of abandoning style altogether, we should cultivate it, use it as a secondary channel, its own medium of communication.

As a fitting example, compare the following two messages I received recently when trying to sell a desk online:

CALL ME. 416-###-####


Hi I am interested in the corner desk you are advertising on craigslist. What are the dimension of the desk? And where in Toronto would I be picking it up from?

When I read these messages, I felt that Emily was more likely to be truly interested in the desk. I felt she would follow through on any commitment she made. I felt she could be believed and trusted. I felt she would let me know if she was going to be late or couldn’t make her appointment. I felt she was friendly and would be a pleasure to deal with.

Emily is now the happy new owner of my corner desk.

She only typed three short sentences, but gave me several paragraphs of information. The former request only typed two words and a phone number. They also gave me several paragraphs of information.

I never called.

The Lost Art Of Proofreading

I am an amateur proofreader; I would like to be a professional proofreader. To date, however, all my work has been volunteer and includes several MSc theses, a few academic papers, numerous Arch Linux newsletters, and two unpublished novels. I enjoy the process of proofreading, of axing unnecessary words, of caressing, cajoling, or cursing the right sound into a written sentence. You see, proofreading is not just about grammar. Its about cadence, flow, style, and rhythm. Above all, its about communication.

And it’s a lost art. I estimate that at least 90 percent of articles on the Internet these days are posted without review or revision. While this is obvious in youtube comments and web forum postings, it also includes countless articles by professional journalists from well-known news agencies. Indeed, some of the worst writing I read each day arrives via Google news results. Independently authored blog articles may be better; they can range from quick thoughtless posts to elegantly crafted prose. Sadly, the majority of authors simply write their article and forget about it.

We are always in a hurry to get information to the masses. News isn’t news if its not new. Why proofread when the information you’re posting is going to be irrelevant in a few hours? First Post! McDonalds has taken over our writing. I want that burger in 43 seconds. Don’t worry about the taste, just serve it quicky. No no, I don’t care if its healthy, I don’t have time to think about that. I’m in a hurry, you see.

I have to get this article posted before my coffee cools down.

It’s a race, a race to provide new information or insights before anyone else. A race that ignores, discards, even condemns quality. A race that defines our society.

Have you ever read something and thought to yourself, “I love how that’s worded. It’s beautiful”? Possibly not — I could be peculiar that way. More often, though, I end up thinking, “What a lovely sentiment; too bad they butchered the wording.” There need to be more beautiful essays. Essays that are a joy to read, and not just a chore to understand.

Style matters.

In four posts to this blog, I have covered an introduction, a software concept, a technical article, and a social discussion. These articles have but one thing in common: I wrote and posted each one immediately. I didn’t proofread them. Sure I read through them once, maybe twice before clicking “Publish”, but that’s not proofreading. Proofreading involves letting the essay marinate for a few hours, maybe days, before posting, then carefully revising — from a reader’s perspective. I didn’t do that.

But this time I will. This post can wait a day or two to be consumed by the public. From now on, that ‘Save Draft’ button is going to get a lot more use.

If you’re not looking to hire a semi-professional proofreader/editor for your next written work, maybe you should think about it. If you think about it, think about me. I’m available and I’m sure we can agree on a rate.