[Development] New Qt example development guideline and revamping examples

[Giuseppe D'Angelo]

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.


> 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.


>     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.


> 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?


> MANDATORY
> 
>     Do not use QT_BEGIN_NAMESPACE ... QT_END_NAMESPACE for example types. This namespace is exclusively for types in the Qt libraries.

This is broken. How is one going to correctly forward declare Qt names 
in a namespaced build of Qt without using those macros? Is there perhaps 
a more comprehensive discussion regarding how to write examples that 
cope with namespaced Qt builds?


Thank you,
-- 
Giuseppe D'Angelo | giuseppe.dangelo at kdab.com | Senior Software Engineer
KDAB (France) S.A.S., a KDAB Group company
Tel. France +33 (0)4 90 84 08 53, http://www.kdab.com
KDAB - The Qt, C++ and OpenGL Experts

-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 4244 bytes
Desc: S/MIME Cryptographic Signature
URL: <http://lists.qt-project.org/pipermail/development/attachments/20230118/4453b548/attachment.bin>