Code taken from a blog post is meant to illustrate an idea. Blogging is literature, not engineering. Don’t build production systems by copying and pasting random code form the Internet. It will not end well.
A reader commented that some of my C code from an earlier blog post is not proper C:
uint32_t random_bounded(uint32_t range) { uint64_t random32bit = random32(); //32-bit random number multiresult = random32bit * range; return multiresult >> 32; }
This is true: the type of the “multiresult” variable to not specified. In that post, I deliberately omitted to specify the type because anyone familiar with C can correctly infer the type. In fact, a large fraction of the code you will find on my blog post is similarly simplified. I often remove special cases, I roll my loops and so forth. That’s because I hope to make it more readable. Real code is often filled with boring details.
It is not that I don’t believe in providing working code. I actually think it is super important and I do it systematically. For example, the post points to the source code in correct C. This blog post is accompanied by a research paper. The research paper points to a GitHub repository that provides reproducible experiments. This code was even peer-reviewed along with the research paper.
However, when someone explains a concept and provides a code sample, I take that as literature, not engineering. You are meant to read the code, not use it as a ready-made reusable artefact.
Simplification is not the same as carelessness. Simplified is not the same as wrong. You should report typographical errors and the like, but if you take the code that served to illustrate an idea, copy it mindlessly in your application code, you have missed a step. You are meant to read the code, not copy it into your production code.
“However, when someone explains a concept and provides a code sample, I take that as literature, not engineering”
How do you reconcile the above with things like the MSDN docs, C++ reference sites, and the like? They provide code samples, what if they decided to do the same as you do? They would be completely useless. To me, those code samples are much more than literature as are posts from people not writing pseudocode in their blog posts.
And you are not writing pseudocode in your posts, you are deliberately taking working code, stripping “boring detail” information from it, and calling it “simplified”. What you are actually doing is making code with bugs in it. You are expecting readers to be able to discern between a bug and what you have intentionally simplified. How do you expect that to work? There is obviously some unknown metric in your own mind that makes you decide what to simplify and what not to. Seems unreasonable to think everyone will know the difference between one of your simplifications and a bug.
How do you reconcile the above with things like the MSDN docs, C++ reference sites, and the like? They provide code samples, what if they decided to do the same as you do? You are expecting readers to be able to discern between a bug and what you have intentionally simplified.
I expect people who read my blog to be smart and knowledgeable. And they are.
If one cannot readily spot the simplification, one is not going to enjoy my blog very much.
Note that I almost always provide full working code… I just don’t include it in the blog posts themselves because the blog posts are meant to be read by human beings, not machine.
How do you expect that to work?
It works. I have been blogging for 15 years and have 40,000 unique visitors a month. Very few people have a problem with simplified code, especially given that a provide full code samples. I am just making this policy explicit.