HACKINGON.NET

The Peter-Principled Pointy-Haired Bureaucrat

liam.mclennan.nospam@nospam.gmail.com (liammclennan) — Thu, 03 Nov 2011 08:17:00 +1000

The phrase that most annoys me in the office is:

"but that's just the way it is. Anyway..."

"but we can't change that"

Blind allegience to the master. This phrase is most often dropped when some potential improvement has become too obvious to simply ignore. It is the beuracrats rallying cry to do nothing and return to the safe and the simple. This is the culture that renders agile retrospectives pointless in many large organisations. The most that can come out of a retro is a list of improvements that will never be implemented. It does not take long before the team develops a social convention that what can't be fixed should not be mentioned, and so the sweeping under the rug is complete.

But it's bullshit. The status quo is not immutable.

Most often, the only forces preventing improvement are laziness, cowardice and politics. Some peter-principled pointy-haired bureaucrat has hoarded power to himself to feed his ego or career prospects.

Corporate I.T. are often the worst offenders. They establish their little fifedom and rule as brutal dictators. They have discovered that the easiest way to secure a network is to render it completely non-functional. I sometimes wonder why they bother with firewalls and proxies when they could simple remove all the network cables. An information worker's computer is a tool to facilitate their work, yet the first thing that happens when new computers are delivered is that I.T. swoops down from Mount Olympus and renders them barely functional.

I feel that if we abandoned the unspoken assumption that waste is acceptable then incompetence would cease to be excusable. We are so accustomed to inefficiency that we no longer notice or care.

Blood and destruction shall be so in use

And dreadful objects so familiar

That mothers shall but smile when they behold

Their infants quarter'd with the hands of war;

All pity choked with custom of fell deeds

Life

liam.mclennan.nospam@nospam.gmail.com (liammclennan) — Sun, 16 Oct 2011 17:33:00 +1000

In high school I had a small and very close group of friends. They were the best friends I have ever had, or will ever have. Five years after we graduated my girlfried (now wife) and I held a fancy-dress party. One of my old school friends was complaining of shoulder pain. He had an appointment with a specialist the next day. The cause of his shoulder pain turned out to be a tumor. A year later he died.

I am sure most people have a similar story that reminds them of their mortality. And there but for the grace of a random universe go I. At the time, I made a commitment (to myself) not to forget my friend, because I knew how easy it is to let someone's memory fade. Five years later I don't think about him every day, but he is in my thoughts a lot. He reminds me to go fast, to create as much value as I can and waste no time. Time is long. Life is short.

My wife and I are expecting our first child in February. Despite every baby name book ever written we have not been able to choose a first name, but we agreed on a middle name straight away - Michael.

Nhibernate Linq, Oracle and comparing to an empty string

liam.mclennan.nospam@nospam.gmail.com (liammclennan) — Wed, 07 Sep 2011 11:03:00 +1000

When you write an NHibernate Linq query you may want to include a predicate to check that a property/field has a value, which might look like this:

person.Email != ""

NHibernate will convert this to a sql expression

Email <> ''

Because oracle evaluates empty strings as null this does not work. The query will never return any rows. The best solution I could find was to use the string length

person.Email.Length > 0

Notes On Problem Solving

liam.mclennan.nospam@nospam.gmail.com (liammclennan) — Sun, 21 Aug 2011 19:04:00 +1000

I have tried to solve many problems in my life, with the solutions created falling roughly into two categories: those that I am proud of and those that I would prefer to forget. Attempting to bias my future towards the former category I spent some time examinging what those successfull solutions had in common, and devised the following heuristic that anecdotally appears to work for me. YMMV. I'm probably stupid. The fact is you may be better off to do exactly the opposite of anything I say.

Heuristic for Successful Problem Solving

Break It Down

Start by decomposing a big hairy problem into many small fuzzy problems. Refine or restart this process until a promising design emerges.

Solve a Little Problem

Pick a small fuzzy problem that provides a logical first (or next) step. Learn as much as possible about the problem domain including everything needed to solve the small fuzzy problem and then a little bit more. This means giving up the implied rule that if you're not typing you're not working. It means reading. And prototyping. And decompiling. I know that I need more knowledge and less typing when I find myself slipping into trial and error.

Record What You Learn

When you're on a role or under pressure it can be difficult but I have found it valuable to make sure that I record what I learn. For a web programmer this is often as simple as recording a significant URL for later reference. Here are some concrete examples:

Write what you have learnt in setting concrete (that's a little joke)
Begin each spike with a set of questions that the spike aims to answer. I use a readme file located somewhere obvious (such as /project/spikes/name_of_spike/readme). When the spike is complete append the answer to each question to the readme.
Record notes in a personal wiki. I have a tiddlywiki in my dropbox. I have been recording notes in the same wiki since July 2005.

Do Not Compromise: Measure Twice, Cut Once

Uncle Bob never tires of reminding us that cutting corners makes us move slower. My anecdotal experience suggests that compromising on the solutions to the small fuzzy problems is a mistake. It makes me slower in the medium and long term. Take the time to get the best solution. Rewrite things. To get it right I often have to do things more than once. Many small things working perfectly are how we build big complicated things that work at all.

Management tend to work by intuition. And refusing to compromise on quality intuitively feels like gold-platting that will hurt budgets and timeframes. But it won't. If the goal is the best solution possible then it will help budgets and timeframes. It may be the only way to hit budgets and timeframes. Your boss may say that you are not being pragmatic because she doesn't realise that doing it properly IS pragmatic. The best solutions are produced when the goal is perfection. The old 'be pragmatic' get it done and out the door attitude leads to mediocraty. This is why I like to work on products, where quality is everything.

If You Are Not Winning Stop

If it's not working, for the love of atheist god, quit, walk away, give up, throw in the towel, and then burn the towel.

It's a little known fact that all of Einstein's greatest breakthroughs occured on the can.

Again, I am writing this down because I know that it is true, yet I find it hard to practive, because it is counter intuitive. It always feel like just one more hack will get me over the line. Once more, slipping into trial and error is a sure sign that things are not right. So stop. Get someone else to take a look at it, leave it until tomorrow or take a walk.

Rich Text Editors (and Microsoft Word) Must Die

liam.mclennan.nospam@nospam.gmail.com (liammclennan) — Wed, 17 Aug 2011 18:58:00 +1000

Rich text editors, by which I mostly mean the WYSIWYG text editors that allow people to create formatted HTML, are a blight upon the internet. Every application I have ever seen that included a rich text editor resulted in the creation of eye-bleedingly hideous content. Take this average example of what happens when information workers get their hands on a WYSIWYG editor:

Now doesn’t that make you want to cry?

This is not an edge case. Content creators consistently give birth to these monsters and no amount of gentle (or rough) cajoling will help. It’s not their fault, they only do what comes naturally and what they should be expected to do. It’s our fault for providing tools with inherent flaws.

Why Does This Happen?

We include rich text editors in applications because they provide instant visual feedback, giving the user a feeling of power and control. But it’s like giving a light saber to a two year old. What follows is my list of reasons why rich text editors must die.

When Everything Is Highlighted, Nothing Is Highlighted

This is the most common and acute symptom or rich text editors. Authors wish to highlight an important point, so they make it bold. But of course the other things they have to say are important too. All of which leads to the truly important idea. By the time they are done, nothing stands out.

I Know It When I See It

A moderately talented information worker is capable of examining published material and expressing an intelligent opinion on the effectiveness of the design. They intuitively ‘feel’ when a design works, but this does not translate into an ability to create good design themself. When it comes to their own work their design-dar is completely useless. The majority of the people creating content do not have the skills to present that content with good design.

Shotgun Surgery

Shotgun Surgery is a software development anti-pattern described as “making a number of small changes to a number of different areas in the code, in order to effect a single, coherent change in behavior”. This situation arises in content formatting if the content creators have been able to include formatting within their content. Imagine having a library of thousands of help files and wanting to change the heading font. If the authors have individually set the heading fonts in each document then you have a big problem.

Consistency

Related to shotgun surgery is the difficulty of enforcing consistency when authors are able to format content themselves. Writing about his experience with documentation in his workplace, Jon Combe discussed:

inconsistencies between documents that make styling and branding across documents a project in itself.

Information Loss

When text is saved as HTML information is lost. Automatic operations against the content becomes difficult. Consider the common example of searching documents. Its easy to search text but searching HTML is tricky. You first need to extract the text from the markup. It would not do to return thousands of results for ‘div’.

Consider the merging of documents. It’s easy to merge text documents programmatically. Merging HTML is problematic because the merged document may be semantically incorrect or malformed. Merging Microsoft Word of PDF documents is close to impossible.

Separation of Concerns

As programmers we know that we should not mix orthogonal concerns, such as content and presentation. They should be defined separately and they should be able to vary independently.

Some Ideas That Almost Work

The democratization of content creation and publishing is one of the drivers of the current technology revolution, so this problem cannot be solved by taking away their crayons. But what if we took away just the coloured ones? Here are some strategies in use today that reduce, but don’t solve the problem.

Reduced Formatting Options

Reduce the text-editor gone mad by disabling as many of the formatting controls as you can get away with. The less power authors have, the less damage they can do.

Reduce Formatting to Styles

The logical conclusion of reducing formatting options is to prevent all formatting other than the application of CSS styles. This actually solves a number of my objections to rich text formatting (but not all).

But What Can I Do?

Step away from the black pit of despair, for their is a solution.

Create Content Using A Semantic Text Language – Such As Markdown

Markdown is an easy-to-read, easy-to-write lightweight markup language. It is extremely close to plain text, with just the most basic formatting commands included. It encourages authors to focus on content and leave presentation as a separate step.

Jon Combe described why markdown (or similar) is the best solution to the rich text editor blues:

Anyone, technical or otherwise, can work with it, we can edit a stylesheet once and keep all documents looking consistent across the product range, and use it to export to HTML and PDF (via pandoc). Sure, Word can do the above, but at the expense of ugly, bloated HTML and inconsistencies between documents that make styling and branding across documents a project in itself.

Jon publishes a markdown editor that you can use to experiment with the syntax. If you use Github, Stack Overflow or FunnelWeb then you have probably already used markdown.

This is an option that will not be popular with users. They WANT full control over the presentation of the document they are creating because:

power always feels good
they don’t realise that their design skills suck
they have not thought about broader issues such as full text search, varied presentation or programmatic manipulation.

Like most medicine it might not taste good at first, but the benefits are enormous, especially to organisations that publish large volumes of material.

I have a dream that one day we will see the end of rich text editors, Microsoft Word and their kind.

I have a dream that one day the overzealous formatters and the semantic text aficionados will be able to sit down together at the table of brotherhood.

PS. I feel a tad guilty about appropriating one of the twentieth centuries greatest speeches to make an insignificant point about content creation, storage and manipulation. To salve my conscience here is a link to the full text of Martin Luther King’s I Have A Dream speech. Read it.

JavaScript Course For Pluralsight

liam.mclennan.nospam@nospam.gmail.com (liammclennan) — Fri, 12 Aug 2011 07:02:00 +1000

It's not exactly news now, but earlier this year I published a course for pluralsight called 'JavaScript Fundamentals'. The course has been doing very well so thank you to everyone who completed it. It's not free - I think you need a $30 monthly subscription to view it.

Why Namespace and Directory Hierarchies Should Not Always Match

liam.mclennan.nospam@nospam.gmail.com (liammclennan) — Wed, 27 Jul 2011 20:04:00 +1000

I tweeted

there are good reasons to have different hierarchies for directories and namespaces. Resharper overruled.

this post adds a brief explanation of what the hell I was talking about.

By default, Resharper encourages us to use a directory hierarchy that matches our namespace hierarchy. Most of the time this is a sensible starting point, but there are some occassions when it is not ideal.

In my current project we group classes by function. Elsewhere, we have other classes that are named by function. The purpose of namespaces is to prevent name collision, but in our case if the namespaces match the directories it actually causes a name collision between the namespace and the identically named class.

Since there is no reason why the classes grouped (in directories) by function need to be in separate namespaces we put them all in the same namespace, thus resolving the name collision.

A Pattern For Injecting Dependencies into JavaScript Modules

liam.mclennan.nospam@nospam.gmail.com (liammclennan) — Sun, 17 Jul 2011 10:33:00 +1000

The obvious and default way of resolving dependencies in JavaScript modules is to do so as needed. In other words, I request a dependency at the point where it is required. The effect of this is to make all modules responsible for resolving the dependencies that they require and to make it nearly impossible to test modules in isolation. Such code often looks like this:

My current preferred solution is to write modules that expose a sinlge variable which is a function that returns the actual module. The input to the function is the modules dependencies. At runtime the function is called with no arguments - so it resolves the dependencies internally. For testing, the function is passed mock dependencies. Here is a module that supports dependency injection:

and an example of using the module with real and fake dependencies:

The examples given use the node.js module syntax, but the pattern works for require.js and probably some other JavaScript module frameworks. This is what I came up with because I could not find any existing work on dependency injection for JavaScript modules. If you can point me to any alternatives I would appreciate it.

Notes on NHibernate Many-to-many Relationships

liam.mclennan.nospam@nospam.gmail.com (liammclennan) — Wed, 06 Jul 2011 18:27:00 +1000

1. Ideally, a many-to-many relationship should be managed by just one end of the relationship. Therefore, the mapping on one end should be inverse. If both ends control the relationship then connecting the two entities can cause duplicate entries in the join table.

2. To delete an entiity that is part of a many-to-many the entity must be removed from the collection that controlls the relationship (i.e. the one that is not inverse)

3. Cascading on many-to-many relationships refers to the other entity, not to the relationship. Cascading deletes is usually a bad idea.

4. By default, fluent nhibernate maps many-to-many relationships using bags. If something is deleted from the bag nhibernate persists the change by deleting (from the database) every record in the bag, and then re-inserting every record except the one that was deleted. If the collection contains a large number of records this could cause a performance problem. A solution is to map the relationship as sets. For fluent nhibernate this means using the AsSet() method on the relationship mapping and using ICollection<> as the type of the collections.

The Expressiveness of CoffeeScript

liam.mclennan.nospam@nospam.gmail.com (liammclennan) — Wed, 08 Jun 2011 20:05:00 +1000

Some time ago I wrote a simple JavaScript function (_properties) to report the non-function properties of a JavaScript object.

the same function, rewritten in CoffeeScript, is:

It is shorter (down from 9 lines to 2) and easier to read.