About Code Snippets

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:

Copy and Paste

Copy and Paste into Production

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.

Copy Paste

Is this a real thing?

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.

This entry was posted in programming. Bookmark the permalink.

3 Responses to About Code Snippets

  1. (Reposting my comment since it was lost in your database disaster today. This worked out well because I mistyped my blog URL anyway!)

    Three years ago you were marking your snippets with a GUID. Do you still try to do this today?

    You’re right about php.net being filled with horrible examples, though they seemed to have fixed a lot of them very recently. A lot of them have been posted to /r/lolphp.

    Reply  |  Quote
  2. Philipp GERMANY Mozilla Firefox Linux says:

    About “Dr. Guttenbergs Copy-Paste”: This is most certainly not a real thing but to mock the former german minister of defence Karl Theodor zu Guttenberg who plagiarised most of his doctorate and had to resign because of it.

    Also: You are making a solid point, I will remember this and just post good code online.

    Reply  |  Quote
  3. Luke Maciak UNITED STATES Mozilla Firefox Windows Terminalist says:

    @ Chris Wellons:

    Thanks for the heads-up about the site crash btw. :)

    Did do that thing with GUID’s at some point, but I got lazy. Plus I’m not actually sure if this actually does anything. It definitely helps to find out the proliferation of your snippet in open-source code online, but it does not help to solve the above problem. People who copy-paste code snippets from a website into production verbatim are unlikely to ever update them.

    A URL on top of the snippet would technically serve the same purpose (also globally unique) but of course websites go down, and copy-pasters are likely to strip “incriminating evidence” such as source URL’s.

    @ Philipp:

    TIL about German politics. Did not intend it to be a political statement – it just came up in Google image search and seemed funny. :P I also forgot all the German I have ever learned (except Die Puppe because it sounds like “ass” in Polish) so I didn’t grok the label below.

    Reply  |  Quote

Leave a Reply

Your email address will not be published. Required fields are marked *