Please improve examples

[Little John]

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

+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

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.

Is it really that hard to write

Code: Select all

EnableExplicit

or

Code: Select all

DisableExplicit

?
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 ...

[Little John]

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.

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).

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.

And add 'enableexplicit' could divert attention from the essential.

This is nonsense ... and by the way, I did not ask for adding EnableExplicit.

In addition, the philosophy of Basic is not to use 'enableexplicit'

Uhh, are you the chair of the international BASIC philosophy association

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.

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.

[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.

[Little John]

Freak, thanks for your reply!

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.

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).

[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.

[Little John]

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.

[Tenaja]

Wiki

[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.

[TI-994A]

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.

[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.

[Little John]

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.

[Andre]

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!

[Tenaja]

Little John: please don't stop to make any suggestions. Your help and exercise here on the forum is very welcome!

+1 !!!

[davido]

@Little John: please don't stop to make any suggestions. Your help and exercise here on the forum is very welcome!

+1

[Little John]

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.)