[kde-guidelines] About code snippets

[Aurélien Gâteau]

On Wednesday 26 June 2013 19:36:35 Thomas Pfeiffer wrote:
> On Wednesday 26 June 2013 18:48:16 Aurélien Gâteau wrote:
> > Was thinking about code snippets lately. I am not sure they are going to
> > happen, as it's a lot of work to create and maintain. An alternative would
> > be to list relevant C++ classes and point to their documentation, which
> > often comes with code snippets (at least for Qt classes, it's less true
> > for
> > KDE classes).
> > 
> > So for example in the ListView page, there would be a section like this:
> > 
> > ---
> > = C++ classes =
> > 
> > * [http://qt-project.org/doc/qt-4.8/qlistview.html|QListView]:
> > single-column list
> > * [http://qt-project.org/doc/qt-4.8/qtreeview.html|QTreeView]:
> > multi-column
> > list
> > ---
> > 
> > This would still be helpful for developers, especially when the class name
> > is not intuitive (example QTreeView for multi-column lists, or
> > KActionSelector for the two-list pattern) and we can easily update it to
> > include QtQuick controls when it makes sense to do so.
> > 
> > What do you think?
> 
> In the Active HIG we use rather minimalistic code snippets for the
> components (see
> http://community.kde.org/Plasma/Active/Development/ActiveHIG/TaskDialogs#Cod
> e_to_Implement_the_Task_Dialog for example). Do you think something like
> that would be feasible and useful?

That is probably feasible, but I'd rather add those snippets to the class 
documentation itself because there is a higher chance they will be kept 
updated by the class maintainers.

Note that I am not necessarily ruling out code snippets, what I would like to 
say is that most (if not all) control guidelines should have references to 
implementation details (C++ classes and later QtQuick controls), we can add 
code snippets for specific, tricky, topics.

Aurélien