QML Best Practices: Coding Standards and Structuring

Coderingsstandaarden dragen bij aan betere codekwaliteit, leesbaarheid, onderhoudbaarheid en samenwerking, wat resulteert in efficiëntere en betrouwbaardere softwareontwikkelingsprocessen. Dit document biedt een uitgebreid overzicht van de QML-coderingsstandaarden en richtlijnen die bij Invisto worden toegepast.

Dit document is opgesteld op basis van onze bevindingen doorheen de jaren, aangevuld met advies van de Qt Group en de open-sourcegemeenschap.

1. Bestandsorganisatie en projectstructuur

1.1 Gescheiden bestanden

Hou elke hoofdcomponent in een eigen QML-bestand. Maak bijvoorbeeld afzonderlijke bestanden voor hoofdviews, herbruikbare componenten en hulpfuncties.

1.2 Naamgevingsconventies

• Geef bestanden de naam van de hoofdcomponent die erin staat, gebruikmakend van PascalCase (bijv. MainView.qml).
• Zorg dat bestandsnamen consistent zijn met componentnamen om verwarring te voorkomen.

1.3 Mapstructuur

Groepeer gerelateerde componenten in mappen, zoals:

• views/ voor hoofdviewcomponenten
• components/ voor herbruikbare of kleinere UI-elementen
• models/ voor datamodellen
• utils/ voor hulpfuncties

2. Componentstructuur en layout

2.1 Minimaliseer nesting

Vermijd overmatige nesting van QML-elementen om de hiërarchie beheersbaar te houden en prestaties te verbeteren.

2.2 Consistente naamgeving van het root-element

Gebruik root als naam voor het root-element in elk QML-bestand. Dit vereenvoudigt referenties, verhoogt de leesbaarheid en zorgt voor een uniforme aanpak.

2.3 Interne data inkapselen

Gebruik een private QtObject binnen een component om interne data te beheren. Dit scheidt UI-elementen van interne logica en bevordert duidelijkheid.

2.4 Gebruik van aliassen en properties

• Gebruik property alias en property om interne properties naar bovenliggende componenten te exposen.
• Vermijd directe toegang tot elementen van buitenaf; gebruik properties voor betere inkapseling.

2.5 Standaardwaarden

• Definieer waar mogelijk standaardwaarden voor properties.
• Gebruik enums voor staten en propertywaarden om leesbaarheid te verbeteren.

3. Vertalingen

3.1 Vertaalbare tekst markeren

Gebruik qsTr voor alle vertaalbare strings, zodat ze worden opgenomen in het Qt-translatiesysteem.

3.2 Onvertaalde tekst herkenbaar maken

Gebruik hoofdletters (bijv. “HELLO” i.p.v. “Hello”) voor onvertaalde tekst om ontbrekende vertalingen gemakkelijk op te sporen.

4. Styling en herbruikbaarheid

4.1 Gebruik Item als basis

Gebruik Item als container wanneer je geen visuele representatie nodig hebt maar wel layout-functionaliteit.

4.2 Stylesheets

Vermijd inline styling; centraliseer styling in herbruikbare stylesheets of globale thema’s.

4.3 Aangepaste componenten

• Gebruik custom QML-componenten voor veelgebruikte UI-patronen (DRY-principe).
• Plaats globale kleuren, lettertypes en margins in een aparte Theme.qml of Styles.qml.

5. Naamgevingsconventies

5.1 Identifiers

Gebruik betekenisvolle, zelfverklarende namen voor objecten, properties en functies.

5.2 CamelCase vs. Snake_Case

• CamelCase voor properties (bijv. backgroundColor) en functies (calculateWidth()).
• PascalCase voor componentnamen (bijv. MainView).

6. Bindings en expressies

6.1 Efficiënte bindings

• Gebruik Connections in plaats van signaalverbindingen in JavaScript voor beter levenscyclusbeheer.
• Vermijd complexe expressies in bindings, omdat ze prestaties kunnen beïnvloeden.

6.2 Gebruik on

Changed

Gebruik deze handlers als er extra logica moet worden uitgevoerd wanneer een property wijzigt.

7. Logica in QML vs. C++

7.1 Minimaliseer logica in QML

Vermijd te veel businesslogica in QML. Verplaats complexe of performancekritische logica naar C++.

7.2 JavaScript modulariseren

Verplaats complexe JS-logica naar aparte .js-bestanden ter bevordering van overzichtelijkheid.

8. Prestatie-optimalisatie

8.1 Vermijd onnodige elementen

Verwijder niet-essentiële elementen en creëer objecten enkel wanneer nodig.

8.2 Lazy loading

Gebruik Loader om zware componenten pas te laden wanneer ze nodig zijn.

8.3 Beperk visuele effecten

Gebruik effecten zoals Opacity, Blur of DropShadow spaarzaam.

8.5 Anchors vs. Layouts

Gebruik anchors voor eenvoudige layouts; deze zijn efficiënter dan GridLayout of ColumnLayout.

9. State- en animatiebeheer

9.1 Gebruik States

Gebruik states om verschillende configuraties van componenten te beheren.

9.2 Declaratieve animaties

Gebruik Behavior of Transition voor animaties. Vermijd procedurele animaties in JS tenzij noodzakelijk.

9.3 Vermijd overmatig animeren

Te veel animaties kunnen afleiden en prestaties beïnvloeden.

10. Foutafhandeling en debugging

10.1 QML-warnings

Let op console-warnings om verouderde of inefficiënte code tijdig te herkennen.

10.2 Debugging

Gebruik console.log() voor debugdoeleinden.

10.3 Foutbeheer

Controleer op undefined properties of bindings, vooral bij dynamisch gecreëerde componenten.

11. Documentatie, commentaar en linting

11.1 Documenteer elke component

Beschrijf kort het doel van de component bovenaan het QML-bestand.

11.2 Inline commentaar

Leg complexe bindings of transitions kort uit.

11.3 Consequente formatting

Gebruik consistente spatiëring en inspringing.

11.4 Linting

Gebruik qmllint voor het opsporen van syntaxfouten, ongebruikte imports en andere kwaliteitsproblemen.

12. Testing en onderhoud

12.1 Property Tests

Gebruik property-based tests om componentgedrag te valideren, vooral bij bindings en animaties.

12.2 Geautomatiseerde UI-tests

Gebruik Qt Test, Squish of andere compatibele tools voor UI-automatisatie en betrouwbaarheid.