Caution: Example Code Ahead

Today's post veers from anything flash specific and goes to the more generic area of example code.  For everything you want learn about in the world of programming there is some example code.  Example code is a great way to see what book authors and blog posters are trying to explain in their posts. I'm a better programmer than a writer so I know how difficult it is to explain some of these concepts without showing code. However, example code has some issues that it is important to be aware of when you use it.

Comments aren't part of the example

Unless you are reading a book about writitng good code ( I recommend Code Complete by Steve McConnell ) the comments in the code are not there to show you good commenting practice. I could rant on and on how code should be self documenting and be able to be read like a good book but my main complaint with comments in most example code is stuff like this:

// define variable a as an integer and set it to 5
var a:int = 5

Now when you are learning about defining and setting variables this comment is important and that is why this comment is in example code. Unfortunately, I see this all too often in code I've had to debug. Code that is straight forward doesn't need to be commented. In case you don't know, comments like that in real world code scream amateur and/or I just copied this from the internet somewhere. Moving forward, you might want to make your code as straight forward as possible so you don't need to comment it.

Best Practices are rarely in example code

Recently I was reading a book on AJAX programming that was trying to show how to use a simple service written in PHP.  To do this they had two input fields in a form where you entered numbers.  The javascript would then send the values of those two fields to a simple PHP webservice that divided the numbers then returned the results. After that the results were parsed to show the answer on the screen.  For the purpose of the book, which was to show how you could use a webservice without being overloaded with other code, this is okay.  In real life, you should just divide the numbers using javascript and leave the webservice out of it.

Also, if you read books and blog posts word for word the authors know that what they are doing isn't meant for prime time so they will leave a caution warning ( possibly with a cartoony icon ) letting you know this. Please heed their advice if it is there, but since it usually isn't just realize that example code probably isn't the best way to handle the problem domain it seems to be solving.

My oh my!

This next section is about a pet peeve of mine, the use of the word "my" in example method and variable names.  For instance, I sometimes run across code like the following:

var myName:String
function myClickHandler( event:Event ):void{
...
}

Unlike the previous examples, I don't think the reasoning behind this convention in example code is strong enough to even use it there. The reason I don't like this convention is the readability of code that has to use it .  Using the myName variable as an example, which code appears cleaner and easier to read?

if( employee.myName == 'Jeff' )

or

if( employee.name == 'Jeff' )

I think you'll agree that the second example, without the redundant prefix is cleaner and easier to read.

The code doesn't always work

Anyone who has ever tried to copy or [GASP!] cuts and pastes example code has probably figured out that there is a high probability that it won't work.  There are several possibilities for this from editors who think they know better to code that was only written in a text editor but not tested or even an errant copy and post from the author's IDE that forgot a semi-colon.

This isn't a problem in the way that the previous items are a problem with example code. Though it would probably be better if it didn't occur, its better just to know that your chances of perfectly working code are 50/50. In fact, non-working example code can be a good thing to debug. Especially when you consider a majority of your programming career ( or hobby for that matter ) will probably be taken up with debugging code that you swear should work.

What else?

While the heading for this section might make you think I'm going to discuss the overuse of if-else statements I'm really asking for your opinions on example code.  Am I off base?  Do you have your own issues with example code? Perhaps you want to discuss the overuse of if-else statements in example code or maybe you'd like to see more of them.  Please, comment below and let me know.

[ad#Adobe Banner] If you liked this post please subscribe to my RSS feed and/or follow me on Twitter. If you only want to see my Flash Friday posts you can follow the subscribe to the Flash Friday feed. How's that for alliteration :) Until next time keep on coding.