feat(poort): bewaak de commentaartaalregel (#518) #720

Merged

brenno merged 3 commits from feat/poort-commentaartaal-518 into main

2026-07-23 10:45:16 +00:00

brenno commented

2026-07-23 10:45:05 +00:00

Owner

Het laatste punt uit #518 waar nog helemaal geen poort voor stond: CONTRIBUTING zegt "Dutch or English, but never both in one comment", en niets mat dat.

Waarom dit wél te bewaken valt, en de taalkeuze niet. Dezelfde gids waarschuwt dat een taalheuristiek die er 5% naast zit slechter is dan geen poort. Dat klopt — voor classificeren: dan moet élk blok een antwoord krijgen en telt elke twijfel mee. Mengdetectie is de andere vraag: die zwijgt tenzij er van béide talen hard bewijs is, dus twijfel levert stilte op in plaats van een vals alarm.

Dartdoc valt er bewust buiten, en dat is de kern van de afweging. Dezelfde gids schrijft vóór dat publieke types in lib/models en lib/services een Engelse dartdoc krijgen — de laag die dart doc, pub.dev en de IDE tonen — met de redenering eronder in de werktaal. Een Engelse samenvattingsregel boven een Nederlandse alinea is dus de gevraagde vorm, en het was 37 van de 47 ruwe treffers. Een poort die de bijdragersgids beboet, wordt uitgezet.

Basislijn tien, en die tien blijven staan. CONTRIBUTING verbiedt het herschrijven van bestaand commentaar alléén om de taal te wijzigen: duizenden regels ruis met andermans redenering onder jouw naam in git blame. Ze zakken vanzelf zodra iemand er om een andere reden aankomt. Alle tien zijn met de hand nagekeken en alle tien echt — van een Engelse alinea met een Nederlandse eronder tot één zin die in het Engels begint en in het Nederlands afloopt (shell_actions.dart:81).

Getoetst in beide richtingen. Groen zegt niets als de regel niet afgaat, dus: met een geplante overtreding valt de poort, en zonder is hij weer groen. Dat was geen formaliteit — mijn eerste versie ging er níét van af, omdat een hoofdletterfilter (bedoeld om typenamen te weren) juist het sterkste signaal wegnam: The … aan het begin van een zin. Zonder die toets was dat gat blijven zitten.

De tests dekken beide kanten: dat hij het mengen vindt, én dat hij zwijgt bij een eentalig blok, bij een Nederlands blok dat een Engelse term citeert, en bij de voorgeschreven dartdoc-vorm.

Bijvangst: een echte fout. De dartdoc van parseDer zat vastgeplakt bovenop die van _maxDerDepth — de constante droeg een samenvatting die niet over haar ging, de functie had er geen. De poort viel erover als "een blok dat halverwege van taal wisselt", en dat was het ook; de oorzaak zat alleen een laag dieper. Eigen commit.

Geregistreerd waar het hoort: Makefile (eigen doel, in check), docs/CHECKS.md (rij + uitleg), check_ratchet_trend.dart (zodat make ratchets hem meeneemt) en CONTRIBUTING.

Poort: make check groen, gedraaid ná de rebase op main met #719 erin.

Refs #518

Het laatste punt uit #518 waar nog helemaal geen poort voor stond: CONTRIBUTING zegt *"Dutch or English, but never both in one comment"*, en niets mat dat. **Waarom dit wél te bewaken valt, en de taalkeuze niet.** Dezelfde gids waarschuwt dat een taalheuristiek die er 5% naast zit slechter is dan geen poort. Dat klopt — voor *classificeren*: dan moet élk blok een antwoord krijgen en telt elke twijfel mee. Mengdetectie is de andere vraag: die zwijgt tenzij er van béide talen hard bewijs is, dus twijfel levert stilte op in plaats van een vals alarm. **Dartdoc valt er bewust buiten, en dat is de kern van de afweging.** Dezelfde gids schrijft vóór dat publieke types in `lib/models` en `lib/services` een *Engelse* dartdoc krijgen — de laag die `dart doc`, pub.dev en de IDE tonen — met de redenering eronder in de werktaal. Een Engelse samenvattingsregel boven een Nederlandse alinea is dus de gevraagde vorm, en het was **37 van de 47** ruwe treffers. Een poort die de bijdragersgids beboet, wordt uitgezet. **Basislijn tien, en die tien blijven staan.** CONTRIBUTING verbiedt het herschrijven van bestaand commentaar alléén om de taal te wijzigen: duizenden regels ruis met andermans redenering onder jouw naam in `git blame`. Ze zakken vanzelf zodra iemand er om een andere reden aankomt. Alle tien zijn met de hand nagekeken en alle tien echt — van een Engelse alinea met een Nederlandse eronder tot één zin die in het Engels begint en in het Nederlands afloopt (`shell_actions.dart:81`). **Getoetst in beide richtingen.** Groen zegt niets als de regel niet afgaat, dus: met een geplante overtreding valt de poort, en zonder is hij weer groen. Dat was geen formaliteit — mijn eerste versie ging er níét van af, omdat een hoofdletterfilter (bedoeld om typenamen te weren) juist het sterkste signaal wegnam: `The …` aan het begin van een zin. Zonder die toets was dat gat blijven zitten. De tests dekken beide kanten: dat hij het mengen vindt, én dat hij zwijgt bij een eentalig blok, bij een Nederlands blok dat een Engelse term citeert, en bij de voorgeschreven dartdoc-vorm. **Bijvangst: een echte fout.** De dartdoc van `parseDer` zat vastgeplakt bovenop die van `_maxDerDepth` — de constante droeg een samenvatting die niet over haar ging, de functie had er geen. De poort viel erover als "een blok dat halverwege van taal wisselt", en dat was het ook; de oorzaak zat alleen een laag dieper. Eigen commit. Geregistreerd waar het hoort: `Makefile` (eigen doel, in `check`), `docs/CHECKS.md` (rij + uitleg), `check_ratchet_trend.dart` (zodat `make ratchets` hem meeneemt) en CONTRIBUTING. Poort: `make check` groen, gedraaid ná de rebase op main met #719 erin. Refs #518

brenno added 3 commits

2026-07-23 10:45:06 +00:00

fix(asn1): de dartdoc van parseDer stond boven de verkeerde declaratie b8cc5c8262

De drie Engelse regels die `parseDer` beschrijven zaten vastgeplakt bovenop de
dartdoc van `_maxDerDepth`. Daardoor droeg de constante een samenvatting die
niet over haar ging, en had de functie zelf geen enkele.

Gevonden door de commentaartaalpoort uit dezelfde tak: het viel op als een blok
dat halverwege van taal wisselt — en dat was het ook, alleen zat de oorzaak een
laag dieper dan een taalkeuze.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

feat(poort): bewaak de commentaartaalregel (#518 ) 7f496dfb09

CONTRIBUTING zegt al een tijd "Nederlands of Engels, maar nooit allebei in één
commentaarblok", en niets mat dat. Van de vijf punten uit #518 was dit het enige
waar helemaal nog geen poort voor stond.

**Waarom dit wél te bewaken valt.** Dezelfde gids waarschuwt dat een
taalheuristiek die er 5% naast zit slechter is dan geen poort. Dat klopt — voor
*classificeren*: dan moet elk blok een antwoord krijgen en telt elke twijfel
mee. Mengdetectie is de andere vraag. Die zwijgt tenzij er van béide talen hard
bewijs is, dus twijfel levert stilte op in plaats van een vals alarm.

**Dartdoc valt er bewust buiten**, en dat is de kern van de afweging. Dezelfde
gids schrijft vóór dat publieke types in lib/models en lib/services een Engelse
dartdoc krijgen — de laag die dart doc, pub.dev en de IDE tonen — met de
redenering eronder in de werktaal. Een Engelse samenvattingsregel boven een
Nederlandse alinea is dus de gevraagde vorm, en het was 37 van de 47 ruwe
treffers. Een poort die de bijdragersgids beboet, wordt uitgezet.

**Basislijn tien, en die tien blijven staan.** CONTRIBUTING verbiedt het
herschrijven van bestaand commentaar alléén om de taal te wijzigen: duizenden
regels ruis met andermans redenering onder jouw naam in `git blame`. Ze zakken
vanzelf zodra iemand er om een andere reden aankomt. Alle tien zijn met de hand
nagekeken en alle tien echt — van een Engelse alinea met een Nederlandse
eronder tot één zin die in het Engels begint en in het Nederlands afloopt.

**Getoetst in beide richtingen**, want groen zegt niets als de regel niet
afgaat: met een geplante overtreding valt de poort, en zonder is hij weer
groen. Dat was geen formaliteit — mijn eerste versie ging er níét van af, omdat
een hoofdletterfilter (bedoeld om typenamen te weren) juist het sterkste
signaal wegnam: "The …" aan het begin van een zin.

De tests dekken beide kanten: dat hij het mengen vindt, én dat hij zwijgt bij
een eentalig blok, bij een Nederlands blok dat een Engelse term citeert, en bij
de voorgeschreven dartdoc-vorm.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs: leg de commentaartaalpoort vast (#518 ) 766a519b7a

CHECKS.md, CONTRIBUTING en de CHANGELOG. De redenering staat erbij en niet
alleen het feit: waarom dartdoc erbuiten valt, waarom mengdetectie wél kan waar
classificeren niet kan, en waarom de tien blokken in de basislijn met opzet
blijven staan.

De aantekening in CONTRIBUTING die zei dat er nog geen poort was, is niet
weggehaald maar aangevuld: dat oordeel gold de dartdoc-clausule en geldt daar
nog steeds — het is precies de reden dat de poort die overslaat.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

brenno merged commit 4fa0cd23ec into main

2026-07-23 10:45:16 +00:00

brenno referenced this pull request from a commit

2026-07-23 10:45:17 +00:00

Merge pull request 'feat(poort): bewaak de commentaartaalregel (#518)' (#720) from feat/poort-commentaartaal-518 into main

brenno referenced this pull request

2026-07-23 10:45:58 +00:00

[Feature] Structural debt: layering, class size, SOURCE_MAP #518

brenno referenced this pull request

2026-07-23 11:24:41 +00:00

[Feature] Structural debt: layering, class size, SOURCE_MAP #518