Wednesday, May 13, 2009

Expecting More From Example Code

While I'm typing this post, I'm actually on vacation.  A road trip to a destination in hopes to relax and unwind from my daily routines.  However, I had to bring the laptop for informational purposes (of course).  On the road, I was thinking about some of the posts that I have created and also of those that I refer back to.  I also compared a lot of these posts against the increased visibility toward the S.O.L.I.D. principles of Object Oriented design.  The more I thought about it, the more I became inspired on the question of should people who read blogs and go to presentations expect more from the authors?

In my opinion, the presentations and the traditional style of technical blog posts are fine.  I feel like they teach a concentrated concept in a, hopefully, straight forward manner.  Some topics provide more practical implementation; however, how many times have you ran across a demo where the variables were only named Foo and Bar?  Presenting a concept is great and effective; however, should more be provided in the examples of in a supplemental post on how to apply the information "properly"?

For example, I wrote a post on using jQuery for different types of visual effects of your elements last year.  It was a very simple post with a moderate amount of code that focused on the topic and didn't deviate.  I, as the author, left it up to the reader to apply this knowledge into their own works.  What if I was to go 1 step further and do a live demo similar to blogs like and  Would that help push the concept better?  What if I supplied a zip file with files that apply the concepts learn in a more real-world scenario?  A lot of my more recent posts include VS projects; however, it is usually a direct reflection of the code inside of the post.  In that jQuery effects posts, I could have easily created a simple directory structure containing the proper files in a traditional/standard method (i.e. separating the CSS and JavaScript into their own directories, etc.).  With regards to my .Net posts, should I make sure that all of my code is commented? Refactored properly to meet the SOLID principles (sans my F# code due to it being functional and not oo)? Include Unit Tests?  I know a lot of people, including myself, who learned some skill by taking someone else's code and then tinkering and tweaking it to learn how things work based on their changes.  I'm wondering if more people would used Unit Testing or "proper" OO design if more of the example code in the blogsphere came with such.

I said earlier that presentations and the traditional blog post is fine as is.  The reason why I say this yet question the example code is that the extra stuff (i.e. Unit Tests, Full Comments, properly design class structures) can sometimes sidetrack the post or presentation.  Questions often rise about these ancillary items as opposed to the concept you are attempting to teach.  So, with that said, I still believe that the posts and presentations are fine.

Should we expect more from the Example Code?  In my opinion, yes.  I know I have a lot of work to do since adding such polish is time consuming; however, if it can assist in improving the overall quality of the code someone else uses, then it'd be worth it.

What do you think?  Should those of us that read blog posts and presentations expect more from the example code tied to such?  Should those of us that author posts provide a more comprehensive look at their code in order to encourage better practices?

What do you think?

kick it on DotNetKicks.comShout it


  1. I think your code samples are great. They don't need to be perfect to be useful. Most of the time when I'm looking for something, I'm just looking for direction and a general idea of things. I'll find something at one blog and maybe it won't answer all my questions but it gets the point across and it'll point me in the right direction, and I'll be able to direct my google searches a bit better.

    I say just put up as much as you can as fast as you can. Don't worry too much about if it makes exact and complete sense. That's the role of books, I think, not blogs. My poor two cents.

  2. Hey J, I think as long as the subject of focus is properly coded, that should be good enough. Adding polish to the code is good, but personally I skip any code that is not related to the subject. Some times excess information confuses the reader.