Writing technical articles is really an art.

It’s not enough to start writing with a very clear goal in mind: you actually need to find a way to take your readers there in a gentle and intuitive way.

The main problem with readers is that they get so easily distracted, so writing your article really boils down to making sure that nothing in the various examples, text or code snippets that you are showing will make them react in a direction that is not the one you are trying to pursue.

Take my previous article called Unit or functional tests?.

In that post, I decided to show the importance of functional tests, and in order to make that point, I made up a code snippet where the ordering of method invocation (which is usually not captured by unit tests) is significant. I initially used the following code:

public class Main {
public void g() {}
public void f() {}
public static void main(String[] argv) {
f();
g();
}
}

Once I was satisfied with the article, I reread it one last time before posting it and I wondered if the use of anonymous method names such as f() and g() were not going to weaken my arguments. I wanted to make sure that anyone reading my code would immediately see that these methods must be run in a certain order, so that I wouldn’t even need to remind it throughout the article.

So I decided to replace f()/g() with names that would be a little more explicit. I picked openFile()/filterFile(). These names are generic enough, and it’s pretty obvious to anyone who can read English that you should open a file before you can filter it.

All the while, I was convinced that I was overthinking the entire problem. Surely, the readers would see that the code is just an example, that the point is not about what this code does, but about the simple fact that by nature, functions and methods *must* be called in a certain order, or your programs break (if you’re not convinced, just go back to whatever code you were working on yesterday and swap two method invocations. Your application will break).

Armed with the conviction that the world needs more explicit and realistic code snippets (boy.kissGirl() anyone?), I went through my draft and replaced f()/g() with openFile()/filterFile().

And sure enough, it was a mistake. Next thing I know, readers start posting comments on how filterFile() should throw an exception, or that it should invoke openFile() internally, and so on… Some readers are so obsessed with the tree that they are completely missing the forest.

It’s very humbling, in a sense, and as the author of this blog, the fault is entirely mine. If I can’t find the right phrasing and interesting examples that will make my readers think, I am not doing my job correctly.

Hopefully, the book that Hani and I are now done writing will not suffer from this problem, but you, dear readers, will be the judges.

And by the way, I was just kidding. I don’t really hate you, I’m sorry I said that.