[Gambas-user] Restructuring the official Gambas examples

Bruce bbruen at ...2308...
Mon Apr 29 01:02:09 CEST 2013


On Sun, 2013-04-28 at 19:30 +0200, Tobias Boege wrote:
> Hi folks,
> 
> {lots} 8<

Hi Tobi,

Here's some "opinion", so take it as such and not criticism.

1) Who uses the examples and why?  
I would say there are two general categories of people who access the
examples. New gambas coders looking for answers to syntax and
algorithmic questions and experienced coders looking for code they have
forgotten how to use (I can confirm there is definitely at least one of
the second type!). The examples need to address both these audiences.

2) Avoiding a plethora of examples
Although having an example focus on a single aspect of gambas is
laudable we do not want to end up with a huge set of examples where one
has to load example B to understand example A, and then example C, D, E
etc. Any code or feature of an example should be completely self
contained.

3) Comments
A sparsely commented class is worse than no comments at all. By this I
mean that comments in example code should go beyond the focus of the
example whenever obscure intent, algorithm or syntax is involved.  If
not, the naive user is left wondering what that piece of the example
code does and how and the experienced user, who may be reviewing the
code because they know that an obscure construct is demonstrated there,
is again frustrated because that exact bit is not commented.
There is no such things as too many or too detailed comments. Oh, how I
know this when having to go back into code I wrote a year, month, week
ago!

cheers
Bruce





More information about the User mailing list