How to write tutorials for beginners ?

For other topics related to the FreeBASIC project or its community.
BasicCoder2
Posts: 3398
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.
So I start with the first step:

Code: Select all

const SCRW = 640
const SCRH = 480
screenres 640,480,32  'set up window

sub 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 x
end sub

drawIt()

sleep

I will skip a couple of interations to this one,

Code: Select all

const SCRW = 640
const SCRH = 480
screenres 640,480,32  'set up window

type BLOB
as single x
as single y
as single vx
as single vy
as single r
as ulong  c
end type

dim shared as BLOB b(1 to 2)
'intialize blobs
b(1).x = 100
b(1).y = 100
b(1).r = 40
b(1).c = rgb(255,0,0)
b(1).vx = int(rnd(1)*3)-1  '-1 to 1
b(1).vy = int(rnd(1)*3)-1
while 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)-1
wend
b(2).x = 200
b(2).y = 200
b(2).r = 40
b(2).c = rgb(255,0,0)
b(2).vx = int(rnd(1)*3)-1  '-1 to 1
b(2).vy = int(rnd(1)*3)-1
while 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)-1
wend

function 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 d
end function

sub 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 x
end sub

sub drawBlob(b as BLOB)
circle (b.x,b.y),b.r,rgb(255,255,255)
end sub

sub 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.vy
end sub

do
screenlock
drawIt()      'draw faded colors
drawBlob(b(1))  'draw circular blob
drawBlob(b(2))
screenunlock
moveBlob(b(1))
moveBlob(b(2))
sleep 2
loop 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

const SCRW = 640
const SCRH = 480
screenres 640,480,32  'set up window

type BLOB
as single x
as single y
as single vx
as single vy
as single r
as ulong  c
end type

const BlobCount = 4

dim shared as BLOB b(1 to BlobCount)

'intialize blobs
for 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 * 8
next i

function 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 d
end function

sub 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 x
end sub

sub drawBlob(b as BLOB)
circle (b.x,b.y),b.r,rgb(255,255,255)
end sub

sub 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.vy
end sub

do
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 2
loop until multikey(&H01)

sleep

MrSwiss
Posts: 3259
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 Demo
ScreenRes(400, 400, 8)  ' 8 bits per Pixel
WindowTitle "Palette DEMO, ScreenRes(400, 400, 8)"

Const BigPix = 24, BPS = BigPix - 1, Offs = 8

For 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
Next
Next

Sleep
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: 9177
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: 363
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
Moderator
Posts: 1629
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: 9177
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: 3398
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.

However your comments and feedback are always welcome.

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

Code: Select all

' Red/Green color mix Demo
const SCRW = 400
const SCRH = 400
ScreenRes(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
Next
Next
Sleep
MrSwiss
Posts: 3259
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
Moderator
Posts: 1629
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: 5937
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 Demo

sub 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+=1
end sub

Main

Sleep
MrSwiss
Posts: 3259
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: 363
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: 3259
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 !!!
2) usually, a Tutorial has a defined Audience (noobs/beginners/slightly advanced/advanced/pro)
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: 3398
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: 3259
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  '' or
Line (x, y)-Step(w, h), clr, BF
The idea is: to not repeat, the same calc. (once only)