The Advantage of Providing Code Samples

Album Cover: Flight of the Conchords

"She's so hot, she's making me sexist."
Flight of the Conchords / Boom

Posted on July 15, 2006 1:15 PM in Blogging
Warning: This blog entry was written two or more years ago. Therefore, it may contain broken links, out-dated or misleading content, or information that is just plain wrong. Please read on with caution.

I'm sure, if you're a programmer like me, you've run into numerous websites or blogs that provide explanations on how to achieve various things through code. I'm also sure you've probably run into articles or blog entries that assume you know enough about the code to read only an explanation of the technique and then turn around and translate that explanation into actual working code.

There is, however, one key advantage (if not more) to providing code samples, even when the explanation seems more than suitable. You can't guarantee that everyone reading your explanation understands the language you're writing it in!

Unless you're so high on the blogger A-list that you've got minions out there localizing your blog (or you're adventurous enough to do it yourself), you need to remember that people may find your entry via search strings like "table height 100%" that don't necessarily mean they speak (or read) English. Having code samples available will often give these visitors what they need without requiring any additional language knowledge.

A good example of this, I suppose, is my recent post titled Embedding YouTube Videos as Valid XHTML 1.0. A German blogger was able to turn around and post a sample for German readers based on information I presented. Luckily for me, English is a well-known language, and chances are the German blogger understood the rest of my entry (especially based on the English Homer Simpson quote I spotted in the blog's sidebar). However, you'd be wise not to base your decision of whether or not to include code samples on this assumption.

Even in cases where the reader speaks the same language as you, code samples are often the easiest, most concise way to get a point across or teach another developer how to get something done.

Comments

Sean on July 16, 2006 at 9:38 AM:

I'm sure you're right. People say mathematics is the universal language, and to some extent, so is programming code.

Beyond that, when sample code is posted, I usually skip the explanation and just read the code. That's very important when I'm using a search engine to find an answer. If I arrive at a site, and don't see code, I hit the back button, and move onto the next site on the list.

Permalink

Ian Clifton on July 21, 2006 at 3:25 PM:

Definitely agreed. Simple code samples often say a lot more than the paragraphs explaining them. If someone understands the programming language well (or, in many cases, just understands programming in general), what the provided code is actually doing is obvious from the code itself. If someone has no clue about programs or webpages, but is looking for an answer to a specific question (e.g. how to redirect a bot), the viewer can often copy and paste the code with minimal knowledge. Plus, you never know when someone might come along, see the way you are doing it, and suggest something different and/or better!

Permalink

Do My Online Class on January 11, 2018 at 3:03 AM:

Science Channel’s are giving a complete knowledge to its viewers about every thing students write done dissertation on this subjects and show its importance.

Permalink

Marketing Research Homework Help on January 11, 2018 at 4:08 AM:

I'm getting excited about this kind of beneficial information of your stuff in the future

Permalink

Post Comments

If you feel like commenting on the above item, use the form below. Your email address will be used for personal contact reasons only, and will not be shown on this website.

Name:

Email Address:

Website:

Comments:

Check this box if you hate spam.