[Development] New Qt example development guideline and revamping examples

[Kimmo Leppälä]

Hi,

Thank you for the proposals Giuseppe!

On 18.1.2023, 14.14, "Development" <development-bounces at qt-project.org> wrote:

On 18/01/2023 10:51, Kimmo Leppälä via Development wrote:
> Also, the guideline is a living document in wiki and we would be happy
> to hear feedback and proposals for it!
>

Here's a few considerations:


>  RECOMMENDED
> Consider also compiling with the more strict warning flags and fix any issues they reveal.

As history shows, this is not going to happen unless we enforce it. The
cmake-magic macros that are used to build examples should set those more
strict flags and enforce them (-Werror).


> Clang
>     Use -Weverything compiler parameter
> Visual Studio
>     Use /Wall compiler parameter

These aren't good recommendations. There's basically no code that
survives those flags, incl. libc++/MS-STL own headers.
Yes, if we enforce with (-Werror) these would be too strict but the warning flags were meant to be enabled without enforcing and then use human judgement if something needs to be fixed.
I changed wiki page to make it clear that consideration should be used and also that focus is on fixing the example codebase, not all the dependencies.

In addition we could define explicit set of warning flags that should be used when enforced with -werror.
Did you already have a list of flags in mind?



> RECOMMENDED
>
>     Prefer signal/slot connection with lambdas: https://doc.qt.io/qt-6/signalsandslots.html

All the contrary, do NOT do that, as it results in 200+ lines unnamed
lambdas. Strongly prefer named slots. Keep the lambdas short and to the
point. Do not use unnamed lambdas.
I changed the wiki page like so:
*Consider using signal/slot connection with lambdas: https://doc.qt.io/qt-6/signalsandslots.html
**Keep lambdas short and to the point
**Don't use unnamed lambdas


>     Check Qt Coding conventions: https://wiki.qt.io/Coding_Conventions

This shouldn't be "recommended" but mandatory. We must follow the same
style in examples as we do in the rest of our code.


>     Consider using clazy plugin (comes also with Qt Creator): https://www.qt.io/blog/porting-from-qt-5-to-qt-6-using-clazy-checks

This should also be mandatory and enforced by CI.
I moved these under mandatory.



> Add example application to correct category, for instance by adding '\meta category {Graphics & UI}' below '\examples'

Is there a list of categories to pick from?
This is still being worked on but should be available this week.
The list will then be linked or included in the guideline document.

-Kimmo
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20230119/a26a3131/attachment.htm>