Vagueness of standard tutorials/examples

For other topics related to the FreeBASIC project or its community.
Eagleon
Posts: 5
Joined: Mar 15, 2007 18:45

Vagueness of standard tutorials/examples

Postby Eagleon » May 20, 2008 16:26

Something has been bothering me consistently while learning Freebasic, and I'm not sure if it's anything that can be helped, but I'm curious if I'm alone or not.

It's very difficult for me to learn anything I don't see an immediate use for - my brain usually just filters out the rest as gibberish. I might learn it superficially if it's something with narrow scope, but it still doesn't stick until I do something that uses it. Obviously this isn't the best thing in the world for something with as much breadth as programming, but I've managed to muddle along so far without the world exploding. Many, many times, going into the Freebasic manual, I've been foiled by this barrier, only to come back to it later on and break through because I've seen something like this:

Code: Select all

Type person_info
  first_name As String
  last_name As String
  house_number As Integer
  street_name As String
  town As String
End Type

That being from the types as objects tutorial. From that I realized that types were a much better solution for defining (for instance) a human's statistics in my game than the one I came up with - namely, having the saved player/npc read into a single array each. This was completely unmanageable because I had to refer back to the order in which each statistic was written into the save to determine what entry I should change.

Reading that tutorial, it's about the only thing I got from it. My eyes glazed over at most of the examples, not because I didn't have the background to understand them, but because foo/bar/x/y don't actually mean anything to me. They aren't problems that need to be solved, therefore it's very difficult for me to focus on what's around them.

I'm not complaining or anything. Given the size of the community, the documentation has obviously been very helpful to most, and I certainly couldn't have gotten anywhere at all without it. But it makes me wonder, how many people are turned off of programming because they can't relate what they see to what they need to do? The reason why I stuck with freebasic past the initial stages was because I already had an understanding of the very basics (excuse the pun) from when I was a kid, writing programs to draw circles in QB, and because of the sensible naming of built-in functions, etc.

Has anyone else had a similar experience with learning to code? I'm open to suggestions on how to get over this hurdle - I usually try looking at code other people have made using the function I need, and that helps sometimes, but I'm at the point where there's usually five keywords I've never even looked at before, and that makes it difficult for me to isolate what's going on.
mambazo
Posts: 652
Joined: Jul 17, 2005 13:02
Location: Ireland
Contact:

Postby mambazo » May 20, 2008 16:59

I had the same experience when trying to read some code that made extensive use of pointers. Took me ages to figure it out. But like you said, it wasn't until I saw them used in a useful and meaningful-naming-convention context that it finally clicked with me. Now I use pointers for just about every project I work on. Dynamic memory allocation has never been the same phrase it once was!

However, what I also know from my years of trial and error, is that, the easier the tutorial is, the easier it is to forget what you learned. So, in that respect, these vague examples/tutorials, are actually more helpful than you imagine. I suppose it depends on the complexity of the subject/method you are trying to figure out.

for me at least, I usually know more about something I never read the manual for, because of all the trial and error experience.
E.K.Virtanen
Posts: 785
Joined: May 28, 2005 9:19
Location: Finland

Postby E.K.Virtanen » May 20, 2008 17:12

Hi.

I do understand what you mean. Problem is that, for experienced programmers, foo and bar are pretty familiar things (eventho they dont mean anything) and they are used in tutorials.

Atleast for beginners it is easier to understand next function than next after it.

Code: Select all

Function RandNumber(MaxNum as Integer) as Integer
     return INT(RND * MaxNum)
End Function


Code: Select all

Function foo(bar as integer) as integer
     return INT(RND * bar)
End Function


In some places, it would be good to spend some room and use variable and function names which does point for the purpose of their use.

But if things are explained too easily, then relationship between learning, understanding and remembering ain't best possible. Thats why it is good if reader needs to spend a bit time and brains to understand 100% what's goin on ;)
Eagleon
Posts: 5
Joined: Mar 15, 2007 18:45

Postby Eagleon » May 20, 2008 17:37

In my experience, the opposite is true, at least for me. If something is explained well and concisely, demonstrated in a useful way, and is easily related to things I would try, I will usually understand it after my first reading. I might not remember syntax, but I'll remember its use, and I'll be able to come back to it without rereading the entire explanation and use it right away. I'll have learned it, literally to the same degree that I would have if I had struggled with understanding it for days.

After I've used it in my code for a while, I won't ever need to go back to the syntax either. Whereas if something is poorly explained, it just frustrates me, and I'll look for other solutions, instead of learning something potentially more useful and flexible, i.e, the Type example.

I'm not saying all useful functions should be handed to the programmer. Besides being virtually impossible, an example is just an example, and even if it happens to be what you want at the time (your RNG example, for instance) sooner or later you're going to want to make something new, or beyond the scope of the function's parameters. It still comes down to effort on the programmer's part, and if they put in that effort, I think they will learn.
Mentat
Posts: 332
Joined: Oct 27, 2007 15:23
Location: NC, US
Contact:

Postby Mentat » May 20, 2008 17:37

Just hang in there. I didn't understand Object oriented programming until I needed it.

Foo and Bar aren't key words. They're just some words often used in examples.

Here's a use for types:

Code: Select all

type foo
     bar as integer
end type

dim myFoo as foo

print "The bar in myFoo is: "; myFoo.bar

myFoo.bar=4

print "Now the value of bar is: "; myFoo.bar

sleep
end


Not only can you have variables in TYPE, but you can also add subroutines and functions.

Such as:

Code: Select all

type dog
     age as integer

     declare sub get_older
end type

sub dog.get_older
     age=age+1
end sub

dim lilly as dog

lilly.get_older
print "Lilly is ";lilly.age
print
print "One year passed"
lilly.get_older
print "Lilly is now";lilly.age

sleep
end
dodicat
Posts: 5978
Joined: Jan 10, 2006 20:30
Location: Scotland

Postby dodicat » May 20, 2008 18:13

A picture paints a thousand words.
We all learn by example, one way or another.If we don't see an example we are left forever wondering.
Foo Bar or not Foo Bar thats what I say.
example:

Code: Select all


sub arrayinsertD(index as integer,insert as double, array() as double )
if index>=lbound(array) and index<=ubound(array)+1 then
    index=index-lbound(array)
    redim preserve array(lbound(array) to  ubound(array)+1)
    dim x as integer
    for x= ubound(array) to lbound(array)+index+1 step -1
      Swap array(x),array(x-1)
    next x
   array(lbound(array)+index)=insert
   end if
end sub
'TEST
dim b(4 to 9) as double
'any old values
b(4)=3.6:b(5)=-5.7:b(6)=.008:b(7)=19:b(8)=-27:b(9)=6
'You want b(6) to be 7, then
arrayinsertD 6,7,b()
'Check it's ok
for x as integer=4 to 10:print "b("; x;") = ";b(x):next x
    sleep
Eclipzer
Posts: 432
Joined: Oct 01, 2005 10:50
Location: Maryland
Contact:

Postby Eclipzer » May 20, 2008 18:27

I personally dislike "foo" and "bar" for the very reasons Eaglon points out. They have absolutely no meaning. What exactly is a "foo"? What is a "bar"? To me, they are poor choices for demonstrating code. As frequently as I use types, looking at the following code posted by Mentat, makes no sense to me:

Code: Select all

Type foo
     bar As Integer
End Type

Dim myFoo As foo

Print "The bar in myFoo is: "; myFoo.bar

myFoo.bar=4

Print "Now the value of bar is: "; myFoo.bar

Sleep
End


I feel even in generic examples you should use variable names that are descriptive, and foobar just doesn't do it IMO. My personal choices when I'm working with completely generic data is to name it after what it actually is:

myVar, myChar, myNum, myInt, myLong, myPtr, myArray, myType, myStruct, myClass, muSub, myFunc, etc.

Even if I can't completely understand the code, I at least know what sort of data is being dealt with in each line of code.

@Eagleon:
You throw variables x,y in with foo,bar, but these sorts of variables actually have meaning from other disciplines, namely mathematics. Here's a brief list:

x,y,z - position coordinates
u,v - texture coordinates
a - acceleration or angle
v - velocity
t - time

Also if you see a variable prefixed with a d, this normally means a delta of that variable.

ex. dx - delta 'x'

Delta simply means change. In code you might see something like:

x+=dx

mambazo wrote:However, what I also know from my years of trial and error, is that, the easier the tutorial is, the easier it is to forget what you learned. So, in that respect, these vague examples/tutorials, are actually more helpful than you imagine.


The difficulty of a tutorial is different than its clarity. Foo bar examples inherently lack clarity, unnecessarily increasing difficulty.


E.K.Virtanen wrote:
But if things are explained too easily, then relationship between learning, understanding and remembering ain't best possible.


Even IF this is true, intentionally making something more difficult to understand does not promote learning it. Imagine being asked to write a book report. The only thing is, the book is encoded, so to actually read the book you had to decode the book first, by hand. Does the action of decoding the book help you understand its contents any better than if the book was already decoded? No, it just slows down the process. This is essentially the same thing.

foo bar is lazy shorthand, plain and simple.
E.K.Virtanen
Posts: 785
Joined: May 28, 2005 9:19
Location: Finland

Postby E.K.Virtanen » May 20, 2008 19:30

Eclipzer wrote:

E.K.Virtanen wrote:
But if things are explained too easily, then relationship between learning, understanding and remembering ain't best possible.


Even IF this is true, intentionally making something more difficult to understand does not promote learning it. Imagine being asked to write a book report. The only thing is, the book is encoded, so to actually read the book you had to decode the book first, by hand


I guess that is bit too overreacted reply? If next example is encoded, then next after it should be ok atleast?

Code: Select all

Function RandNumber(MaxNum As Integer) As Integer
     Return Int(Rnd * MaxNum)
End Function


Code: Select all

Function RandNumberBetween0andMaxNum(MaxNumToRandomize As Integer) As Integer ' Function randomizes a number between 0 and MaxNumToRandomize and returns it as integer
     Return Int(Rnd * MaxNumToRandomize) ' Returns randomed value between 0 and MaxNumToRandomize
End Function ' End of this function
dodicat
Posts: 5978
Joined: Jan 10, 2006 20:30
Location: Scotland

Postby dodicat » May 20, 2008 19:37

Mentat wrote:Just hang in there. I didn't understand Object oriented programming until I needed it.

Foo and Bar aren't key words. They're just some words often used in examples.

Here's a use for types:

Code: Select all

type foo
     bar as integer
end type

dim myFoo as foo

print "The bar in myFoo is: "; myFoo.bar

myFoo.bar=4

print "Now the value of bar is: "; myFoo.bar

sleep
end


Not only can you have variables in TYPE, but you can also add subroutines and functions.

Such as:

Code: Select all

type dog
     age as integer

     declare sub get_older
end type

sub dog.get_older
     age=age+1
end sub

dim lilly as dog

lilly.get_older
print "Lilly is ";lilly.age
print
print "One year passed"
lilly.get_older
print "Lilly is now";lilly.age

sleep
end

Mentat
I like your example of Lilly. It paints a picture of a little black dog with greyish whiskers.
A little touching also, for I have a little dog and how I hate to see her get older.
The help examples in most languages are cryptic, and I don't understand why. Probably to get you to think, but that hurts.
I've saved your TYPE with subroutine and called it Lilly, hope you don't mind.
Examples are the best - always. Foo and Bar are confusing, but they are there along with Hello World.
Long live Lilly
Eagleon
Posts: 5
Joined: Mar 15, 2007 18:45

Postby Eagleon » May 20, 2008 20:43

E.K.Virtanen wrote:

Code: Select all

Function RandNumber(MaxNum As Integer) As Integer
     Return Int(Rnd * MaxNum)
End Function


Code: Select all

Function RandNumberBetween0andMaxNum(MaxNumToRandomize As Integer) As Integer ' Function randomizes a number between 0 and MaxNumToRandomize and returns it as integer
     Return Int(Rnd * MaxNumToRandomize) ' Returns randomed value between 0 and MaxNumToRandomize
End Function ' End of this function


Okay, let's say you had a new keyword you were trying to understand. Let's call it 'switch', and let's make it change anything put into its parameters to perfect German, in several different dialects.

You don't know (gaspe) the internals of this keyword or how it works because that's beyond you, for now. You do know what it's for, and that you want to find out what goes into using it.

However, in order to do so, first you have to give it information. Cue generic example:

Code: Select all

dim fud as integer
dim foo(0 to 5) as string
dim bar(0 to 5) as integer
dim ff as integer
dim result(0 to 5) as string

sub load (file as string, file2 as integer)
    ff = freefile
   open file for input as ff
    DIM IO (0 TO 5) AS String
    do until fud = 6
        input FF,foo(fud)
        fud += 1
    loop

    close ff
    ff = freefile
    open file2 for input as ff
    fud = 0
    do until fud = 6
        input ff,bar(fud)
        fud += 1
    loop
    close ff
end sub

load("trans.txt","dia.txt")
fud = -1
do
    fud += 1
    result(fud) = switch(bar(fud),foo(fud))
    print result(fud)
loop until fud = 5


It's perfectly functional (I hope, hehe), except for the switch keyword. But it's not a very good example for teaching how to use it.

You might argue that the file IO is strange and frivolous to put in there, and you'd be right. I thought it'd be funny to include, sue me :P The point is that yes, you know what Rnd does. Just about everyone does right away upon seeing it used in context, because it's similar to Rand, which is similar to random. But some keywords are not so obvious, and those are the ones that seem to me to need context in the information around them.

If you knew that the first parameter (bar) is always the dialect code, and the second (foo) is the string you wanted to translate, it'd be easier, but you'd probably still need to search your memory for what the tutorial or example said it was, and that breaks up the flow of understanding even further. It is also difficult to separate the actual information going into Switch from the variables of the rest of the program, which is another problem, I think, with many of the examples I've seen. Granted this is a dramatization, but sometimes not by much when you look at the stuff that's out there :P
Lachie Dazdarian
Posts: 2338
Joined: May 31, 2005 9:59
Location: Croatia
Contact:

Postby Lachie Dazdarian » May 20, 2008 21:28

I've learned best from non-generic tutorials; tutorials that deal with a specific problem and definitely include example(s). Anyway, that's what I'm trying to do with my tutorials. But then again, I mostly deal with game design and that's applied programming. What about people who just want to learn generic programming? I think it's best for them to learn from generic tutorials and not examples dealing with specific problems. At least in the beginning.

I think it all depends on why you want to learn programming.
badmrbox
Posts: 659
Joined: Oct 27, 2005 14:40
Location: Sweden
Contact:

Postby badmrbox » May 20, 2008 22:07

Eclipzer wrote:I personally dislike "foo" and "bar" for the very reasons Eaglon points out.
I agree with you there.
Basic Coder
Posts: 180
Joined: Aug 02, 2006 23:37
Location: Australia

Postby Basic Coder » May 20, 2008 22:49

Lachie Dazdarian wrote:I've learned best from non-generic tutorials; tutorials that deal with a specific problem and definitely include example(s). Anyway, that's what I'm trying to do with my tutorials. But then again, I mostly deal with game design and that's applied programming. What about people who just want to learn generic programming? I think it's best for them to learn from generic tutorials and not examples dealing with specific problems. At least in the beginning.

I think it all depends on why you want to learn programming.


I learn things as I need them. And I think game programming
covers just about everything you need to know and can vary
from the simple to the complex. Also game programming can
provide very good examples of using OOP.

Basic Coder
yetifoot
Posts: 1710
Joined: Sep 11, 2005 7:08
Location: England
Contact:

Postby yetifoot » May 21, 2008 5:45

I think you are right in a way about foo and bar being used in examples as a bad thing. For a very short theoretical example, often there isn't a good real life example to show, but often you can come up with something better.

I think I did overuse the foo/bar in my 'types as objects' tutorial, looking at it now, I see at least a few places I could have contrived some semi-real example instead, and it's correct to say I use it as a lazy shorthand.

However, even if I make up some use for it, it may not be appropriate for all, if I had chosen some game scenarios, then people into some other area may have had their eyes glaze over if they don't understand games, or thought it was of no use to them. It's a tough call.

I had never thought about the foo/bar issue like this before, however one of my existing regrets on that tutorial is related, I wish I had finished on a serious real world example. That and i'm not convinced on the "beginners" in the name, my use of beginners there should probably be read as "used to freebasic and pointers and stuff, but not type objects"

It's never too late however, and like I've wanted to go back and add that full example at the end, I now also want to tweak some of that foo/bar stuff, hopefully I will get around to that at some point.

I very much agree with the general theme of most documentation for FreeBASIC not being so good for a total novice. A lot of it may assume non-familiarity with FB, but also assume some programming experience in another language(in particular QB).

Some people, for example RDC with his book, have tried to rectify this. I don't envy them much as it's a tough thing to teach. Even though I have taught people to program in the past, that was face to face, immediate feedback, I could answer any queries straight away, and try and present in a different style/context. it's a different world to write a good solid tutorial that anyone can follow. I have tried to write those type of tutorials in the past, but never published anything, as I felt it was not up to standard.
wallyfblu
Posts: 69
Joined: May 24, 2006 10:58
Location: ITALY

Postby wallyfblu » May 21, 2008 6:36

Eclipzer wrote:
I personally dislike "foo" and "bar" for the very reasons Eaglon points out.

badmrbox wrote:
I agree with you there.


I agree with you too. I have a lot of effort to learn from non-specific examples and focus what they mean. However I understand the difficult to write general purpose examples that satisfy everybody.

Return to “Community Discussion”

Who is online

Users browsing this forum: No registered users and 2 guests