Please improve examples

[Little John]

This is not a bug report, but a suggestion for improvement of the documentation.
However, I didn't find a better thread for posting it.

Summary:
Several examples in the help can be improved by using constants with meaningful names, rather than using 0 for different purposes.

In several examples in the help, 0 is used pretty often with different meanings. This is didactically not good, and can even be confusing as was recently seen here on the forum. The following code illustrates the problem (It's the second example from the "Prototypes" chapter, with just comments and some blank lines removed.):

Code: Select all

Prototype.i ProtoMessageBoxW(Window.i, Body.p-unicode, Title.p-unicode, Flags.i = 0)

If OpenLibrary(0, "User32.dll")
   MsgBox.ProtoMessageBoxW = GetFunction(0, "MessageBoxW")
   MsgBox(0, "Hello", "World")
EndIf

If someone wants to use OpenLibrary() with #PB_Any rather than a self-chosen constant, then the first changes might look like this:

Code: Select all

lib = OpenLibrary(#PB_Any, "User32.dll")
If lib

That's fine so far.

Now s/he replaces all occurences of 0 with lib and thus gets this code:

Code: Select all

Prototype.i ProtoMessageBoxW(Window.i, Body.p-unicode, Title.p-unicode, Flags.i = 0)

lib = OpenLibrary(#PB_Any, "User32.dll")
If lib   
   MsgBox.ProtoMessageBoxW = GetFunction(lib, "MessageBoxW")
   MsgBox(lib, "Hello", "World")
EndIf

But this code is not working anymore!
This is because the 0 used with the MsgBox() function has a different meaning than the other zeros here, and must not be replaced with lib

The proper code with #PB_Any is:

Code: Select all

Prototype.i ProtoMessageBoxW(Window.i, Body.p-unicode, Title.p-unicode, Flags.i = 0)

lib = OpenLibrary(#PB_Any, "User32.dll")
If lib   
   MsgBox.ProtoMessageBoxW = GetFunction(lib, "MessageBoxW")
   MsgBox(0, "Hello", "World")
EndIf

So a didactically better version of the original example code is:

Code: Select all

Prototype.i ProtoMessageBoxW(Window.i, Body.p-unicode, Title.p-unicode, Flags.i = 0)
#Library = 0

If OpenLibrary(#Library, "User32.dll")
   MsgBox.ProtoMessageBoxW = GetFunction(#Library, "MessageBoxW")
   MsgBox(0, "Hello", "World")
EndIf

There are other example codes in the help, that contain even more zeros for different purposes (window number, gadget number etc.). Those examples can be pretty confusing, especially for beginners.


BTW, since I'm on the subject right now:
Another improvement of example codes would be, to make them ready for usage with EnableExplicit. So I actually would write the respective examle code like this:

Code: Select all

Prototype.i ProtoMessageBoxW(Window.i, Body.p-unicode, Title.p-unicode, Flags.i = 0)
Define MsgBox.ProtoMessageBoxW
#Library = 0

If OpenLibrary(#Library, "User32.dll")
   MsgBox = GetFunction(#Library, "MessageBoxW")
   MsgBox(0, "Hello", "World")
EndIf

[skywalk]

YES!
I would prefer we force EnableExplicit always on.
Without it, code is wide open for bugs and automation tools must be nearly as intelligent as the compiler.

[normeus]

+1
I think better examples would really help acquire more users, and dare I say "younger programmers".
Maybe something can be setup where we collaborate with HTML formated examples so it could be easier to add to the help file:

Code: Select all

<title>FileSize()</title>
<h2>Example</h2>

<code=Purebasic>
fname$="example.txt"
If FileSize(fname$) > 0
     debug "file exist and has readable content"
Else
      debug "File does not have content or is a directory"
 EndIf
</code>

I know, its a dumb example, but the HTML is what I wanted to show.

Norm.

[Bitblazer]

+1

Several examples teach a very questionable coding style to beginners. I realize that the examples arent meant to teach coding style, but actually by repeatedly showing a bad style to beginners, you shouldnt be surprised if thats what they use.

and if you say "Too bad for them, but who cares? The purebasic documentation isnt a beginners course to programming!"

Well a beginner who gets frustrated due to not finding a bug thanks to learning a bad style like this, is likely somebody you lose in the long run - either to another hobby or language ... and there you lose a future customer and deal with a shrinking community.

[davido]

+1

[Tenaja]

A wiki, and we could help fix this...

[Andre]

Good points! But as this is something general (the "style" of PB codes), which would need the adapting of a lot of code examples in the PB manual, I wait for a comment of Fred here...

[Mijikai]

I would also 'force' EnableExplicit

In the beginning i never used it and though i dont need it... obviously a mistake
Now i always use it (i also use End btw.).

I think it would be a good thing to have it only as check box option in the compiler settings that by default is always on.

[Bitblazer]

If Fred creates a wiki with the pb existing example codes, links to them in the manual, copy&pastes the existing ones to the wiki and gives a few trustable community members editing rights - i am pretty sure a mutual clean standard can be agreed upon and all examples being reformatted, adjusted, enhanced and new ones probably added

ps: yes enableexplicit is a must. I consider the fact that such a switch is even optional, as part of a more wild history Its the first command in every source i write with PB.

[BarryG]

EnableExplicit: Optional, yes. Mandatory, no. I don't want it always on when I just need to test some quick code from scratch, because it wastes my time declaring all the variables. That's part of PureBasic's charm: it's quick and easy to write some short code. The user can always use EnableExplicit for their release executables, if they wish.

[Lord]

EnableExplicit: Optional, yes. Mandatory, no.
...

[Denis]

+1
EnableExplicit by default will be good.

[Mesa]

I let Fred answer, if he wants but from my point of view, this will not happen because the small examples of the documentation must be understandable at first sight. So we will keep a '0' rather than a '#pb_any'. There are here to illustrate a function, not to be used 'as is'. And add 'enableexplicit' could divert attention from the essential.

In addition, the philosophy of Basic is not to use 'enableexplicit' but to have the choice to use it, unlike the philosophy of C-like languages, so why put it in all the examples.

I can add in the doc that the use of 'enableexplicit' is recommended for large projects or to avoid typing errors if you like.

Mesa.

[DK_PETER]

Revised examples: Sure.

Is it really that hard to write

Code: Select all

EnableExplicit

or

Code: Select all

DisableExplicit

?
Extremely redundant request...

[Little John]

Good points! But as this is something general (the "style" of PB codes), which would need the adapting of a lot of code examples in the PB manual, I wait for a comment of Fred here...

Thank you, Andre.