This will be an exercise in brevity. Originally I wanted to post this thought on Twitter, but I could not figure out how to compress it into 140 characters. I could have posted it on Google+ but I figured I might as well publish it somewhere where at least few people will actually read it.
Let’s say you made a thing: be it a function, a library, a framework or perhaps a utility of some sort. You publish it online for the world to see, and as it is our ancient custom, you provide a working example to show users how it works. This example typically takes a form of a concise code snippet that aims to showcase how your thing works. Here is something a lot of people don’t think about when they post code snippets online: what happens with them afterwards. Here is a hint:
This is a well known fact: most code snippets that get posted online, invariably find their way into production code somewhere. No matter how many dire warnings you post before, after and even inside the snippet, someone, somewhere will straight up copy and paste it directly into their mission critical production environment. If your code includes an obvious security hole, or stealthy hisen-bug waiting for specific use case to manifest, it will be enshrined there forever. Even if you fix it on your page, the buggy version will likely never get updated.
There is nothing you can do about it, and the potential problems this could cause will be on them, but… Now that you know this, you can take steps to ensure that snippets you publish online are of high quality, and that examples you use are actually appropriate. I think the best example of this was from in the vast repository of terrible code snippets that is php.net where one of the contributors said something along the lines of
this function is not rated for crypto and should not be used for authentication, but let me show you how to generate random salts with it. I can’t remember where exactly I have read this, and it might have been excised and nullified by now. Still, you should take my word for it, because I have a blog which means means I am a journalist, and journalists have integrity. Integrity is a fancy way of saying their shit is legit.
Unfortunately, making sure your code is of high quality not enough. If your example is long, boring and complicated, someone is bound to take it, rip out important, crucial chunks and post a simplified, buggified and incomplete version for all of the world to see. And then people will use that snippet because it is short, and easier to grok on the first glance. I know this, because I have done this. I’ve been on both ends of this equation.
By that I mean that more than once I have taken a snippet of code, deleted lines I did not comprehend or care to research. As long as the resulting abridged version compiled I typically declared victory, and triumphantly vomited it onto the internet via a blog post or two. Not on this blog of course, but in other places. Actually, maybe on this blog too… Yeah, this definitely happened on this blog, didn’t it?
I’ve been on the other side too. Went to the official documentation site and found it wanting and so I copied and pasted from somewhere else. Not into production of course… Actually, probably into production. But if something works, it works, until it doesn’t and then you blame it on the intern. Preferably the one that no longer works here, for plausible dependability.
I guess what I’m saying is that any code you post online not only ought to be correct and feature the best, most secure way of doing things. It should also be concise to the point of being irreducible. Because if it isn’t, someone will reduce it for you, and then we are back to square one. How do you accomplish such a feat? It’s easy: pick good defaults.
Whenever you make something, the easiest way to call or execute it should always fall back onto the “right” defaults, and follow best practices. The people who want to half-ass things, jerry-rig or tinker then can boot-strap their own little disasters by passing parameters or using command line switches or what not. But the clean and concise way should always try to do the right thing. Of course this is not always possible, but it never hurts to try.