new kde-examples module

[Thiago Macieira]

Em Quarta-feira 02 Setembro 2009, às 13:17:37, você escreveu:
> hello everyone ..

Hi Aaron

> i am creating a new module that will sit in trunk/ called kde-examples. the
> point of this module will be to collect all of our small example apps into
>  one place.

Nitpicking: it should be called "kdeexamples", without the dash :-)

> this will:
> 
> * make it easier for people to find as they will all be in one place
> 
> * make it easy to ship as it will be distilled out of kdelibs and other
> modules
> 
> * make a great pairing for our generated developer documentation
> 
> the module would not be shipped as part of KDE Software Distribution
>  releases, but would be made available for download as a source package
>  from, e.g., techbase.
> 
> if there are any objections to this plan, please speak now before i do more
> work.

I think this is a good idea. Examples for our APIs and frameworks are always 
welcome. Benefits of having them are:

* shows new developers how to use KDE API
  also shows existing developers how to use API they don't know yet

* shows everyone the power of KDE APIs, how far you can go

* like you said, complement the API docs
  I would go further and say that we should extend our API docs with links to 
  examples

* examples help in debugging bugs in our libraries, where unit tests don't go


As for the examples themselves, they should:

* show the technology, obviously

* be simple and to the point (the app doesn't have to be fully functional)

* be very well commented / documented

* be easy to read (clear coding style is important)

* not contain hacks

* not use any private API (out of the question)

* avoid #ifdef like the plague

* wherever possible, be cross-platform


One thing I'd like to add is that we should strongly encourage lib developers 
to write examples for _all_ their new API, along with unit tests. Sometimes, 
tests are difficult to make when the API is very high up in the integration 
scale, but an example should be doable.

[Wherever I wrote API, you can replace with any kind of functionality that can 
be used outside of the original lib/app. For example, extensions to Konqueror, 
plugins to applications, scripts extending app functionality, etc.]

I don't want to say it's a mandatory thing to do, because some developers are 
there for the fun and don't think that writing examples is fun. They may be 
discouraged from making a lib contribution that would be valuable just because 
they have to write an example.

It is mandatory in Qt, but most of Qt development comes from paid engineers 
(it spills over to contributions, though). New APIs must always have 
documentation written and reviewed, the API must be reviewed, there has to be 
a comprehensive set of unit tests (we're introducing coverage tests now) and 
there have to be examples.

I think it's a good policy and we should implement it as much as we can and 
makes sense for KDE.

Sidenote: we can help with the API reviews. For small things, it's doable over 
IRC. For large things, it's very time-consuming however. One thing we 
discussed about a year ago was to organise "trips to Oslo" for developers to 
interact with our team and do an API Review the Qt Way. This has been 
forgotten a bit, but I'll ping our marketing to get this organised. (I just 
fear a truckload of Nokia developers might sign up too)

-- 
Thiago Macieira - thiago (AT) macieira.info - thiago (AT) kde.org
  Senior Product Manager - Nokia, Qt Development Frameworks
      PGP/GPG: 0x6EF45358; fingerprint:
      E067 918B B660 DBD1 105C  966C 33F5 F005 6EF4 5358

Qt Developer Days 2009 | Registration Now Open!
Munich, Germany: Oct 12 - 14     San Francisco, California: Nov 2 - 4
      http://qt.nokia.com/qtdevdays2009
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part.
URL: <http://mail.kde.org/pipermail/kde-core-devel/attachments/20090902/b26c71eb/attachment.sig>