It is currently Thu Oct 24, 2019 3:45 am

All times are UTC + 1 hour




Post new topic Reply to topic  [ 6 posts ] 
Author Message
 Post subject: Please improve examples
PostPosted: Sun Sep 01, 2019 12:27 pm 
Offline
Addict
Addict
User avatar

Joined: Thu Jun 07, 2007 3:25 pm
Posts: 3680
Location: Berlin, Germany
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:
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:
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:
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:
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:
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:
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

_________________
Please excuse my flawed English. My native language is PureBasic.
Search
RSBasic's backups


Last edited by Little John on Sun Sep 01, 2019 2:19 pm, edited 1 time in total.

Top
 Profile  
Reply with quote  
 Post subject: Re: Please improve examples
PostPosted: Sun Sep 01, 2019 2:16 pm 
Offline
Addict
Addict
User avatar

Joined: Wed Dec 23, 2009 10:14 pm
Posts: 3089
Location: Boston, MA
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.

_________________
The nice thing about standards is there are so many to choose from. ~ Andrew Tanenbaum


Top
 Profile  
Reply with quote  
 Post subject: Re: Please improve examples
PostPosted: Mon Sep 02, 2019 2:44 pm 
Offline
Enthusiast
Enthusiast

Joined: Fri Apr 20, 2012 8:09 pm
Posts: 280
+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:
<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.

_________________
google Translate;Makes my jokes fall flat- Fait mes blagues tombent à plat- Machte meine Witze verpuffen- Eh cumpari ci vo sunari


Top
 Profile  
Reply with quote  
 Post subject: Re: Please improve examples
PostPosted: Mon Sep 02, 2019 5:24 pm 
Offline
Enthusiast
Enthusiast

Joined: Mon Apr 10, 2017 6:17 pm
Posts: 274
Location: Germany
+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.

_________________
webpage


Top
 Profile  
Reply with quote  
 Post subject: Re: Please improve examples
PostPosted: Mon Sep 02, 2019 6:46 pm 
Offline
Addict
Addict

Joined: Fri Nov 09, 2012 11:04 pm
Posts: 1681
Location: Uttoxeter, UK
+1

_________________
DE AA EB


Top
 Profile  
Reply with quote  
 Post subject: Re: Please improve examples
PostPosted: Mon Sep 02, 2019 11:49 pm 
Offline
Addict
Addict
User avatar

Joined: Tue Nov 09, 2010 10:15 pm
Posts: 1548
A wiki, and we could help fix this...


Top
 Profile  
Reply with quote  
Display posts from previous:  Sort by  
Post new topic Reply to topic  [ 6 posts ] 

All times are UTC + 1 hour


Who is online

Users browsing this forum: No registered users and 1 guest


You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum

Search for:
Jump to:  

 


Powered by phpBB © 2008 phpBB Group
subSilver+ theme by Canver Software, sponsor Sanal Modifiye