[Gambas-user] Some more example projects to be distributed with gambas

[BB]

On 2/9/23 8:37 pm, Martin Fischer wrote:
>>
>> Are the "example" programs well documented?
>>
>> you can post them here...
>> http://gambaswiki.org/wiki/app <http://gambaswiki.org/wiki/app>
>>
>> and here...
>> https://forum.gambas.one/viewforum.php?f=13&sid=02b6ad70ecd1d329705bcd041622459e. 
>> <https://forum.gambas.one/viewforum.php?f=13&sid=02b6ad70ecd1d329705bcd041622459e.>.. 
>>
>>
>> There's a few other forums too.
>>
>> BruceS
>>
>
> Hi Bruce,
>
> now I'm confused...
>
> First of all, "well documented" is very subjective.
> - Are these examples as well documented as the other examples
> distributed with gambas? Yes :-)
> - Are they documented good enough? Depends. They try to show a single
> thing. They are minimal. Not much documentation needed then. But surely
> they do not explain all knowledge that is required to build them. For
> example: the database examples use a DataSource control and arrange the
> data-bound controls as children of it. Why? That's something the gambas
> documentation shall explain. It's not documented as part of the example.
> And that's fine.
>
> After this rant: here's how I see it as a learner of gambas:
> When I want to learn something new I do:
> 1. Read the documentation.
> 2. Go over tutorials. I used the examples distributed with gambas for
> that. Some were helpful, some not. That's normal.
> 3. Write my own examples to familiarize myself with the ecosystem.
>
> The examples distributed with gambas are tutorials. This means:
> - there shall be many of them...
> - each area of gambas shall be covered by at least one example
> - each example shall focus on one topic only (sure: not always possible)
>
> This means that an example is not some random app that someone wrote to
> solve a real (business-)problem. They are meant to be educational!
>
> I see the apps mentioned in the wiki and hosted on the software farm as
> the real application that do something useful.
>
> To sum this up:
> - educational, tutorial-style examples: distributed with gambas
> - real apps: hosted on software farm and/or mentioned in the wiki/app
>
> Am I wrong with this view?
> What is your take on this?
>
> Regards,
> Martin
>
> ----[ http://gambaswiki.org/wiki/doc/netiquette ]----

Some may disagree but I reckon that well documented means a total 
overload of everything you thought of while writing that code. In 
defense and after a decade or so of revisiting my own sometimes years 
old code, the phrases "FIIK if I know what I was tying to do here" and 
similarly "WTF is this real" oft pop into mind. Even then sometimes the 
"assumptions" astound me ("Where the hell did you get the idea that this 
database query will always return a non-zero result?", "Why does 
nullifying a list based control mean that I cant find the row that I 
just deleted a moment ago?" "Who wrote this **** anyway?" etc).

These days I have taken a leaf out of the un-lamented Ward Cunningham's 
doctrine and usually start writing a "story" inside any new procedure to 
try and explain to myself 
what-it-is-thet-it-is-thet-I-am-trying-to-do-here. Unless the proc is 
evidently so simple as to be taken for granted.

You know what? Documentation costs, bucketloads on Monday, a few shekles 
on Tuesday, a grain of sand on Friday, possibly a groat next week. But a 
concubines ransom thereafter.

ymmv

The other bruce