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

[BB]

On 2/9/23 8:59 pm, BB wrote:
>
> 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
>
Sorry, that last one should have been "But a lack of documentation will 
cost you a concubines ransom thereafter."