## How to write tutorials for beginners ?

For other topics related to the FreeBASIC project or its community.
BasicCoder2
Posts: 3311
Joined: Jan 01, 2009 7:03

### How to write tutorials for beginners ?

When explaining something like OOP or some algorithm it needs to be in incremental steps as I suspect we all originally learnt it ourselves. This saves a lot of work dissecting even a well commented program which may use techniques or maths which a beginner may not be familiar with. I see a lot of examples where it is left to the reader to figure out how the code works.
For example paul doe used the metaball code but how does the metaBall code actually work?
viewtopic.php?f=15&t=26050
Here it is explained in steps.
This video example actually uses functions not part of the FreeBASIC standard set such as dist() so you have to write them yourself.

Code: Select all

`const SCRW = 640const SCRH = 480screenres 640,480,32  'set up windowsub drawIt()    dim as single dx,dy,d    for x as integer = 0 to SCRW-1        for y as integer = 0 to SCRH-1            dx = abs(x - SCRW/2)            dy = abs(y - SCRH/2)            d = sqr(dx^2 + dy^2)            if d > 255 then d = 255            pset(x,y), rgb(d,d,d)  'each color a function of x and y        next y    next xend subdrawIt()sleep`

I will skip a couple of interations to this one,

Code: Select all

`'https://www.youtube.com/watch?v=ccYLb7cLB1Iconst SCRW = 640const SCRH = 480screenres 640,480,32  'set up windowtype BLOB    as single x    as single y    as single vx    as single vy    as single r    as ulong  cend typedim shared as BLOB b(1 to 2)'intialize blobsb(1).x = 100b(1).y = 100b(1).r = 40b(1).c = rgb(255,0,0)b(1).vx = int(rnd(1)*3)-1  '-1 to 1b(1).vy = int(rnd(1)*3)-1while b(1).vx = 0 and b(1).vy = 0  'don't want zero movement    b(1).vx = int(rnd(1)*3)-1  '-1 to 1    b(1).vy = int(rnd(1)*3)-1wendb(2).x = 200b(2).y = 200b(2).r = 40b(2).c = rgb(255,0,0)b(2).vx = int(rnd(1)*3)-1  '-1 to 1b(2).vy = int(rnd(1)*3)-1while b(2).vx = 0 and b(2).vy = 0  'don't want zero movement    b(2).vx = int(rnd(1)*3)-1  '-1 to 1    b(2).vy = int(rnd(1)*3)-1wendfunction dist(x1 as single,y1 as single,x2 as single, y2 as single) as single    dim as single dx,dy,d    dx = abs(x1-x2)    dy = abs(y1-y2)    d = sqr(dx^2+dy^2)    if d > 255 then d = 255    return dend functionsub drawIt()    dim as single dx,dy,d    dim as ulong  col    for x as integer = 0 to SCRW-1        for y as integer = 0 to SCRH-1            d = dist(x,y,b(1).x,b(1).y)            if d > 0 then                col = b(1).r*255 \ d            end if            if col > 255 then col = 255            pset(x,y), rgb(col,0,0)  'each color a function of x and y        next y    next xend subsub drawBlob(b as BLOB)    circle (b.x,b.y),b.r,rgb(255,255,255)end subsub moveBlob(b as BLOB)    b.x = b.x + b.vx    if b.x < 0 or b.x > SCRW then b.vx = -b.vx    b.y = b.y + b.vy    if b.y < 0 or b.y > SCRH then b.vy = -b.vyend subdo    screenlock    drawIt()      'draw faded colors    drawBlob(b(1))  'draw circular blob    drawBlob(b(2))      screenunlock    moveBlob(b(1))    moveBlob(b(2))    sleep 2loop until multikey(&H01)sleep`

And this is the stage I got to tonight which actually has a visual bug in it which never the less shows the blending of blobs so I will leave it as is until tomorrow night when I will continue watching the tutorial and translating the code examples.

Code: Select all

`'https://www.youtube.com/watch?v=ccYLb7cLB1Iconst SCRW = 640const SCRH = 480screenres 640,480,32  'set up windowtype BLOB    as single x    as single y    as single vx    as single vy    as single r    as ulong  cend typeconst BlobCount = 4dim shared as BLOB b(1 to BlobCount)'intialize blobsfor i as integer = 1 to BlobCount    b(i).x = int(rnd(1)*SCRW)    b(i).y = int(rnd(1)*SCRH)    b(i).r = 40    b(i).c = rgb(255,0,0)    b(i).vx = int(rnd(1)*3)-1  '-1 to 1    b(i).vy = int(rnd(1)*3)-1    while b(i).vx = 0 and b(i).vy = 0  'don't want zero movement        b(i).vx = int(rnd(i)*3)-1  '-1 to 1        b(i).vy = int(rnd(i)*3)-1    wend    'speed them up    b(i).vx = b(i).vx * 8    b(i).vy = b(i).vy * 8next ifunction dist(x1 as single,y1 as single,x2 as single, y2 as single) as single    dim as single dx,dy,d    dx = abs(x1-x2)    dy = abs(y1-y2)    d = sqr(dx^2+dy^2)    if d > 255 then d = 255    return dend functionsub drawIt()    dim as single dx,dy,d,sum    dim as ulong  col    for x as integer = 0 to SCRW-1        for y as integer = 0 to SCRH-1                        sum = 0            for i as integer = 1 to BlobCount                d = dist(x,y,b(i).x,b(i).y)                if d > 0 then                    sum = sum + b(i).r*180 \ d                end if            next i                        'if sum > 255 then sum = 255                        pset(x,y), rgb(sum,0,0)  'each color a function of x and y                    next y    next xend subsub drawBlob(b as BLOB)    circle (b.x,b.y),b.r,rgb(255,255,255)end subsub moveBlob(b as BLOB)    b.x = b.x + b.vx    if b.x < 0 or b.x > SCRW then b.vx = -b.vx    b.y = b.y + b.vy    if b.y < 0 or b.y > SCRH then b.vy = -b.vyend subdo    screenlock    drawIt()      'draw faded colors    for i as integer = 1 to BlobCount        drawBlob(b(i))  'draw circular blob    next i      screenunlock    for i as integer = 1 to BlobCount        moveBlob(b(i))    next i    sleep 2loop until multikey(&H01)sleep`
MrSwiss
Posts: 2812
Joined: Jun 02, 2013 9:27
Location: Switzerland

### Re: How to write tutorials for beginners ?

@BasicCoder2,

sorry, but this style of coding is not suitable, to be taught to beginners, because:
it introduces 'shared' variables, where there is no reason to use them
it'll teach bad coding style (again, 'shared' variables)
it's not reusable (the procedures, because of (again and again) 'shared' variables use)
it's slow (with minor changes, far more efficient)
This is by all means, just the tip of the iceberg.

A little example of a efficient double loop:

Code: Select all

`' Palette DemoScreenRes(400, 400, 8)  ' 8 bits per PixelWindowTitle "Palette DEMO, ScreenRes(400, 400, 8)"Const BigPix = 24, BPS = BigPix - 1, Offs = 8For j As UInteger = 0 to 15    Var y = j * BigPix + Offs               ' calc. y-Axis    For i As UInteger = 0 to 15        Var x = i * BigPix + Offs, _        ' calc. x-Axis            c = j * BigPix + i              ' calc. new Color        Line (x, y)-Step(BPS, BPS), c, BF   ' show Box filled    NextNextSleep`
Btw: the var's in this example resolve to 'Integer', as the const's do.
The original code isn't by me, just the re-coding ...
fxm
Posts: 8424
Joined: Apr 22, 2009 12:46
Location: Paris (suburbs), FRANCE

### Re: How to write tutorials for beginners ?

No lucky !
x, y and c are UInteger, as i and j.
I do not recommend beginners to use Var with mathematical expressions but only with simple terms.
(I never use Var because I prefer to control the definition of types rather than trust the compiler with my eyes closed)
dasyar
Posts: 335
Joined: Dec 04, 2008 15:31

### Re: How to write tutorials for beginners ?

I do not see a problem with using shared, as long as their is a comment that states that it is a global designation for the variable, as opposed to a local designation. I am sure that topic would come up very quickly.

As part of the "hand holding" process, I think all code examples should be heavily commented. And for that reason, I think not to many coders would take on any meaningful tutorials. But that is just my opinion.
Imortis
Posts: 1579
Joined: Jun 02, 2005 15:10
Location: USA
Contact:

### Re: How to write tutorials for beginners ?

fxm wrote:(I never use Var because I prefer to control the definition of types rather than trust the compiler with my eyes closed)

You and me both.
fxm
Posts: 8424
Joined: Apr 22, 2009 12:46
Location: Paris (suburbs), FRANCE

### Re: How to write tutorials for beginners ?

Likewise, I use only very exceptionally Shared.
(I prefer to pass this type of variable as argument of the called procedure)
Last edited by fxm on Nov 02, 2017 20:40, edited 1 time in total.
BasicCoder2
Posts: 3311
Joined: Jan 01, 2009 7:03

### Re: How to write tutorials for beginners ?

Of course the primary purpose here was to show how a program might develop in increments of understanding of the algorithm. At some stage we all began in small steps and often someone who can sum it up in a few comments forget that understanding the comments may be assuming knowledge a beginner does not have.

I do see a lot of advanced programmers talking among themselves which is fine but beyond my ability to participate.

Yes I should not use global variables if avoidable.
I seem to remember pointers to bitmaps are required to be shared due to something about memory stack space?
I think the dist() function is stand alone if I take out the 255 limit test and move that to the main.
For me I use readability and understanding first, speed efficiency second.
I always use 32 bit color.

In this example I might suggest to uncomment the sleep to see it "in action".

Code: Select all

`' Red/Green color mix Democonst SCRW = 400const SCRH = 400ScreenRes(SCRW,SCRH, 32)WindowTitle "RED/GREEN MIX PALETTE DEMO"For j As UInteger = 0 to 15    For i As UInteger = 0 to 15        'draws color block at i*25,j*25        line (i*25,j*25)-(i*25+23,j*25+23),rgb(i*16,j*16,0),bf        'sleep    NextNextSleep`
MrSwiss
Posts: 2812
Joined: Jun 02, 2013 9:27
Location: Switzerland

### Re: How to write tutorials for beginners ?

BasicCoder2 wrote:For me I use readability and understanding first, speed efficiency second.

Code: Select all

`line (i*25,j*25)-(i*25+23,j*25+23),rgb(i*16,j*16,0),bf`
There is another one (non-readable), for a beginner, IMHO.
Like I've suggested before: take calculations out of, parameter's.
Using var or pre-defined helper-variables ... then line command simpler:

Line (x, y)-Step(w, h), clr, BF '' using w/h relative, to x, y

dasyar wrote: I think all code examples should be heavily commented. And for that reason, I think not to many coders would take on any meaningful tutorials. But that is just my opinion.
You've got it the wrong way around, I usually write commented code, but don't at all like,
to write prose (the actual text, of a tutorial).
Just as a example Library Tutorial.
Last edited by MrSwiss on Nov 02, 2017 20:37, edited 3 times in total.
Imortis
Posts: 1579
Joined: Jun 02, 2005 15:10
Location: USA
Contact:

### Re: How to write tutorials for beginners ?

BasicCoder2 wrote:For me I use readability and understanding first, speed efficiency second.

Well said. I think a simple, inefficient block of code is better for learning than a complicated efficient one. I had a programming teacher in college who would always say, "The correct answer to a coding problem is the one that works." When you are learning, how you get that is not as important as THAT you get that.

Also, while I understand the aversion to shared variables, I don't think that keeping them our of tutorials is a great idea. A tool is a tool. Seldom are there bad tools. Usually it is a case of people using them badly.
dodicat
Posts: 5245
Joined: Jan 10, 2006 20:30
Location: Scotland

### Re: How to write tutorials for beginners ?

I have made Mr Swiss's piece even easier, it has no loops to grapple with and is now modular.

Code: Select all

`' Palette Demosub Main    static as long g=1,i,j    g+=1    if g<16*16 then Main else ScreenRes(400, 400, 8):WindowTitle "Palette DEMO, ScreenRes(400, 400, 8)"    Const BigPix = 24, BPS = BigPix - 1, Offs = 8    i+=1    Var y = j * BigPix + Offs               ' calc. y-Axis    Var x = i * BigPix + Offs, _            ' calc. x-Axis            c = j * BigPix + i              ' calc. new Color        Line (x, y)-Step(BPS, BPS), c, BF   ' show Box filled        if i >=15 then i=-1:j+=1end subMainSleep `
MrSwiss
Posts: 2812
Joined: Jun 02, 2013 9:27
Location: Switzerland

### Re: How to write tutorials for beginners ?

Hi dodicat,

<... easier and modular> lol, great, would you perhaps care, to comment on your "enhancements".
dasyar
Posts: 335
Joined: Dec 04, 2008 15:31

### Re: How to write tutorials for beginners ?

I think maybe a question should be asked - what is your definition for tutorial. If I was a rank raw beginner and I saw some of the code examples that were shown here, I would definitely be scratching my head, and thinking what the heck is going on. And that would even be after studying the code. And in fact that is what I am doing right now, scratching my head trying to understand what the code is supposed to be doing.
MrSwiss
Posts: 2812
Joined: Jun 02, 2013 9:27
Location: Switzerland

### Re: How to write tutorials for beginners ?

dasyar wrote:I think maybe a question should be asked - what is your definition for tutorial.
Well, there is more than just a short sentence:
1) A Tutorial is never, an excuse, for not reading the Manual !!!
3) the Tutorial I've pointed to, would be ranked: "slightly advanced" (no noobs/beginners)
Apart from that, Tutorials can be "pointed" to a specific topic: "writing a (static) Library" is this case ...
(you should know, how to write procedures: sub's/function's, before diving into that one)
BasicCoder2
Posts: 3311
Joined: Jan 01, 2009 7:03

### Re: How to write tutorials for beginners ?

MrSwiss wrote: There is another one (non-readable), for a beginner, IMHO.
line (i*25,j*25)-(i*25+23,j*25+23),rgb(i*16,j*16,0),bf

Maybe. I understand such code by visualization.

Code: Select all

`'        0         i*25    i*25+23'      0 +-----------o------o-------- x axis'        |           |      |'        |           |      |  'j*25  o-----------########'        |           #      #'        |           #      #'j*25+23 o-----------########'        |'        |'       y-axis`

Ideally you would be able to use drawings as part of the explanation:

Code: Select all

`screenres 640,480,32 line (174,149)-(321,290),rgb(255,100,100),bf line (238,217)-(413,372),rgb(100,255,100),bf 'green sprite 1 line (50,50)-(174,149),rgb(255,0,0),b line (50,50)-(321,290),rgb(255,0,0),b line (174,149)-(321,290),rgb(255,0,0),b line (175,150)-(320,289),rgb(255,0,0),b 'red sprite 1 line (50,50)-(238,217),rgb(0,255,0),b line (50,50)-(413,372),rgb(0,255,0),b line (238,217)-(413,372),rgb(0,255,0),b line (239,218)-(412,371),rgb(0,255,0),b line (238,217)-(321,290),rgb(100,100,0),bf'current coordinate of scanning loops line (50,50)-(280,247),rgb(50,50,255),b'draw screen coordinates line (50,50)-(566,50),rgb(255,255,255) line (50,50)-(50,433),rgb(255,255,255) 'shared point on screen i,j circle (280,247),5,rgb(0,0,255) draw string (22,28), "(0,0)" color rgb(255,0,0) draw string (157,33), "s1.x" draw string (307,33), "s1.x+s1.w" draw string (4,145),"s1.y" draw string (0,278),"s1.y+s1.h" color rgb(100,100,255) draw string (30,245),"j" draw string (280,33),"i" color rgb(0,255,0) draw string (224,33),"s2.x" draw string (404,33),"s2.x+s2.w" draw string (12,205),"s2.y" draw string (0,360),"s2.y+s2.h" sleep`

Personally I don't find the -Step method the most readable I only see it as a short cut.
.

@dasyar,
Well my code was supposed to be showing understandable incremental stages of the algorithm of a metaball demo as explained in the utube video.
A tutorial of the language itself would also be in incremental steps. It was the pointing out that an explanation depends on where the reader is at. To give the complete solution without showing how that solution was reached is not a tutorial although it may be an explanation to someone who is good at reading code and immediately see how it works.
.

@dodicat,
maybe main() should always be used.
.

Ultimately it is the person who is reading the tutorial that gets to decide if they understood it or not.
.
MrSwiss
Posts: 2812
Joined: Jun 02, 2013 9:27
Location: Switzerland

### Re: How to write tutorials for beginners ?

BasicCoder2 wrote:Personally I don't find the -Step method the most readable I only see it as a short cut.
I don't understand you, about 2 years ago, when we where discussing Draw-Editor's,
you've used relative positioning, all the time?

However, the main point, is different:
assume variables are declared (for quickness)

Code: Select all

`'' pre calculate variables ...x = i * 24 : y = j * 24 : w = boxw - 1, h = boxh - 1 Line (x, y)-(x + w, y + h), clr, BF  '' orLine (x, y)-Step(w, h), clr, BF`
The idea is: to not repeat, the same calc. (once only)