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...