Page 2 of 3
Re: Please improve examples
Posted: Thu Mar 05, 2020 7:04 pm
by Little John
Mijikai wrote: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.
This doesn't have got much to do with what I wrote in the first post of this thread.
Feel free to start a discussion about that in a separate thread, but don't hijack this one
Denis wrote:+1
EnableExplicit by default will be good.
Maybe someone is interested in the fact, that I (deliberately!) never wrote that ...
This is a different discussion. Feel free to discuss that in your own thread, but don'*t hijack this one
Little John wrote: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
There is no
EnableExplicit at all in that code. But the trick is:
That code runs with
EnableExplicit on or off, so it is always usable!
In contrast, the following code (similiar to that one in the help)
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
only runs with
EnableExplicit off, but not with
EnableExplicit on.
DK_PETER wrote:Is it really that hard to write
or
?
Extremely redundant request...
I never requested that, and this has nothing got to do with what I wrote in my original post here.
However, it's old news hat some people like to post offtopic stuff in other people's threads ...
Re: Please improve examples
Posted: Thu Mar 05, 2020 7:25 pm
by Little John
Mesa wrote: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.
The examples in the help are for learning. And that's the reason why I wrote what I wrote.
Mesa wrote:So we will keep a '0' rather than a '#pb_any'.
Nobody said that '0' should be replaced with '#pb_any'.
You didn't even read what I wrote (or you didn't understand it).
Mesa wrote:There are here to illustrate a function, not to be used 'as is'.
The examples in the help are for learning. That's why I mentioned the term "didactics". Obviously, you don't know much about that subject.
Mesa wrote:And add 'enableexplicit' could divert attention from the essential.
This is nonsense ... and by the way, I did not ask for adding
EnableExplicit.
Mesa wrote:In addition, the philosophy of Basic is not to use 'enableexplicit'
Uhh, are you the chair of the international BASIC philosophy association
Mesa wrote:but to have the choice to use it,
With my suggestion, people do have the choice to use it (see explanation in my previous post).
With the examples in the PB help as they currently are, people do
not have the choice: The current examples can only be used without
EnableExplicit. So if you want users to have the choice, you should appreciate my suggestion.
Mesa wrote:I can add in the doc that the use of 'enableexplicit' is recommended for large projects or to avoid typing errors if you like.
This has nothing got to do with what I wrote in my first post here.
Re: Please improve examples
Posted: Thu Mar 05, 2020 7:43 pm
by freak
We try to keep the code examples short and leave out anything that is not needed to demonstrate the immediate use of the command. This is why there are no calls to FreeXXX() or CloseXXX() commands in the examples either unless they are necessary. Adding constant declarations or definitions for variables (which would be needed for EnableExplicit readiness) falls in the same category.
The examples are for reference. They are there to show a minimum working example of the command with as little context as needed. More complete examples can be found in the Examples folder.
Re: Please improve examples
Posted: Thu Mar 05, 2020 7:53 pm
by Little John
Freak, thanks for your reply!
freak wrote:The examples are for reference. They are there to show a minimum working example of the command with as little context as needed.
Yes, obviously. And my suggestion is to change that.
freak wrote:More complete examples can be found in the Examples folder.
That's appreciated. However, it does not compensate for the fact that many examples are
especially for beginners didactically rather poor and even partly confusing (for details please see my first post in this thread).
Re: Please improve examples
Posted: Fri Mar 06, 2020 3:34 am
by IdeasVacuum
+1
a) Diagrams - a picture paints a thousand words
b) Meaningful example - does not have to be a full-blown App but a working example that does not ignore the nuances of the function.
Re: Please improve examples
Posted: Sat Mar 07, 2020 5:58 pm
by Little John
freak wrote:More complete examples can be found in the Examples folder.
In the meantime, I've taken a closer look at the eamples in the Examples folder. Unfortunately, many of them also suffer from the problems that I mentioned in the first post of this thread!
And regardless whether we are talking about short examles as part of the documentation (.CHM file), or about more complete examples in the Examples folder ... the main purpose of examples is (read: should be)
teaching users (especially beginners) how to use the respective commands and functions properly, and how to write good and safe programs. And in this regard, there is room for improvement. I explained that in detail in my first post here, and several other forum members agreed. Also, ommitting calls to FreeXXX() or CloseXXX() in the examples is not a good idea.
Note: I don't expect the PB documentation (or anything else) to be perfect. However, when someone makes a reasonable suggestion for improvement, I then expect that the Fantaisie team would recognize it, rather than rejecting it outright, and thus
deliberately providing didactically poor examples.
Re: Please improve examples
Posted: Sat Mar 07, 2020 6:40 pm
by Tenaja
Wiki
Re: Please improve examples
Posted: Sat Mar 07, 2020 6:43 pm
by freak
I explained our reasons for keeping the examples short. Your opinion on that differs and we respect that. But please respect ours as well.
Re: Please improve examples
Posted: Sat Mar 07, 2020 7:07 pm
by TI-994A
freak wrote:We try to keep the code examples short and leave out anything that is not needed to demonstrate the immediate use of the command. This is why there are no calls to FreeXXX() or CloseXXX() commands in the examples either unless they are necessary. Adding constant declarations or definitions for variables (which would be needed for EnableExplicit readiness) falls in the same category.
The examples are for reference. They are there to show a minimum working example of the command with as little context as needed. More complete examples can be found in the Examples folder.
I'd have to agree, as this makes perfect sense.
The core command reference should not be cluttered with extraneous code.
The suggestions for expanded and intuitive examples are perhaps more suited as content for the
User Guide.
Re: Please improve examples
Posted: Sat Mar 07, 2020 7:11 pm
by skywalk
I am in the camp of deeper is better.
Flimsy examples only wet an appetite or worse leave out subtleties in a larger context.
The many 1 or 4 line examples should be omitted.
This lack of immediate single line examples would force the reader to search elsewhere.
Ideally, the docs would provide a roadmap/hyperlink to approved examples that actually mean something.
This would drastically alter the trajectory of the forum coding questions and the many nooby bug reports.
A handful of topically focused examples would impart the best principles of PureBasic coding and free the doc's and its editors from the mundane.
I count dozens of rich examples from many contributors(TI-994A,RASHAD,mk-soft,srod,infratec,thorsten,danilo, too many to list all).
The work is done. The doc's merely have to link.
Re: Please improve examples
Posted: Sat Mar 07, 2020 8:31 pm
by Little John
freak wrote:I explained our reasons for keeping the examples short. Your opinion on that differs and we respect that. But please respect ours as well.
Sorry! I was shocked by your answer, and I think I probably wasn't sure whether or not that was just a dream. Now I realize that it's reality.
There is no need for me to offer my decades of experience as a teacher to people who are not interested in it. So I'll stop making suggestions here on the forum, that will save both you and me some time.
Re: Please improve examples
Posted: Sat Mar 07, 2020 9:07 pm
by Andre
TI-994A wrote:freak wrote:The examples are for reference. They are there to show a minimum working example of the command with as little context as needed. More complete examples can be found in the Examples folder.
I'd have to agree, as this makes perfect sense.
The core command reference should not be cluttered with extraneous code.
The suggestions for expanded and intuitive examples are perhaps more suited as content for the
User Guide.
I agree here, the UserGuide is probably the best place for this more expanded descriptions and examples.
This was also the reason for me, to start the following thread in the PB forum:
viewtopic.php?f=7&t=45842
@Little John: please don't stop to make any suggestions. Your help and exercise here on the forum is very welcome!
Re: Please improve examples
Posted: Sat Mar 07, 2020 9:31 pm
by Tenaja
Little John: please don't stop to make any suggestions. Your help and exercise here on the forum is very welcome!
+1 !!!
Re: Please improve examples
Posted: Sat Mar 07, 2020 9:53 pm
by davido
Andre wrote:
@Little John: please don't stop to make any suggestions. Your help and exercise here on the forum is very welcome!
+1
Re: Please improve examples
Posted: Sat Mar 07, 2020 10:21 pm
by Little John
Andre wrote:I agree here, the UserGuide is probably the best place for this more expanded descriptions and examples.
This was also the reason for me, to start the following thread in the PB forum:
viewtopic.php?f=7&t=45842
Hello Andre,
please note that I did not suggest writing much expanded or so to say "bloated" examples.
My main suggestion was/is, not to use '0' everywhere in an example where it is technically possible, but to use meaningful named constants instead. I think this would just add 2 or 3 lines to an average example. (And (almost) everyone would immediately see the improvement of readability of the code.)