Thoughts on Examples

GPS - Tue Feb 26, 2002: Often times I think about what is the perfect example to demonstrate a way of doing something with Tcl. The common thought I have is whether or not to make the code reusable or to make things more clear through less reusability. I can recall that when I was first starting to program I was frequently frustrated by people using variables rather than values in examples. It seems like having more than 2 variables in a complex proc was too much for me. Introducing upvar and uplevel into the idea is akin to trying to teach someone how to use pointers (which is often confusing to new programmers).

With some of my examples I have hardcoded paths rather than represented a widgets path with a variable, simply because I feel it makes it more understandable when trying to grasp a new concept. Another thing to consider is the relative ability of the viewer.

Somewhere along the way I developed the ability to store more variables in my mind when reading source code (I still have problems with recursion though). Is there a method to help programmers train their minds for this kind of task? Perhaps this is like advanced math, but more broken down into parts. Are there any books dealing with training your mind to handle general complex ideas? Do most programmers visualize the objects or data in their heads? Is visualization the key?

What are your thoughts about this?

Arjen Markus Just a few remarks: it is a very basic question, and I have no particular answer to this. My personal view is this: when I program, I mostly deal with "things", they should do something or something should be done to them. I think I visualise the result in my mind - like juggling with path names and the like. But then I am very visually and textually oriented.

Being visually oriented is certainly not the same as being addicted to drawing involved diagrams as one does with design methodologies like UML. Frankly, I detest them. A piece of text is much better - in my personal universe - than a bunch of drawings that are inadequately trying to tell a story.

A good example should show the essence:

• If you want to show the idiom of dealing with path names and file names, then show the proper commands for this.
• If your major concern is how to deal with errors that may arise in opening and reading files, do not mess up the example with complicated manipulations of the former kind.
• If you want to provide a receipe for dealing with files in general (so combining the above two), show both idioms, but well separated.
• Manipulating numbers is best done via variables: who would recognise 86400 as the number of seconds in a day? Who would recognise the value 3.14152 (any one who thinks he/she does is wrong :-) Use a mnemonic name - these are recognisable, numbers are not.

LV writes: I always advocate clearly documenting when you are showing code that can be used as a 'archtype' vs code that is being used to demonstrate some small point. To often users look at one piece of code and copy that code everytime they want to code an example of that command - if best practices are not used as the basis for writing said code, one quickly finds oneself with a storehouse of potentially broken code...