racket skill bijgewerkt

racket-skill.md

@@ -52,7 +52,7 @@ Voor publieke functies:
 - Houd `provide` en `require` eenvoudig en overzichtelijk.
 - Voeg geen extra framework, wrapperlaag of generieke infrastructuur toe zonder concrete noodzaak.
 
-## pre/postcondities
+## Beschrijving van functies
 
 Geëxporteerde functies/procedures/classes of functies/procedures/classes die daarvoor duidelijk in 
 aanmerking komen, d.w.z. die die provided zijn of naar verwachting zullen worden, moeten gedocumenteerd worden.
@@ -60,20 +60,31 @@ Zowel in een module scribble als in de code zelf. In het engels.
 
 In de code zelf: minimaal:
 
+```racket
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ; goal   : <doel>
 ; pre    : <preconditie(s)>
 ; post   : <postconditie(s)>
 ; [result:] <resultaat en onder welke conditie>
+; [internals:]
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+```
+
+Als een functie/procedure/class overduidelijk in aanmerking komt voor 'provide' en hij staat er nog niet in.
+Verzamel dan de lijst en vraag of je ze moet toevoegen. 
 
 Over het algemeen wil ik de internals van een functie weten. Hoe werkt het en waarom werkt.
 Beschrijf die in de sectie 'internals'.
 
-; [internals:]
-;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+### Beschrijving van functies in het algemeen
 
-Als een functie/procedure/class overduidelijk in aanmerking komt voor 'provide' en hij staat er nog niet in.
-Verzamel dan de lijst en vraag of je ze moet toevoegen. 
+Iedere functie die wordt gedefinieerd, tenzij een lokale helper functie van maximaal 5 regels
+krijgt in ieder geval één commentregel met:
+
+```racket
+;;; <explain what this function does and it's meaning in the module.
+;;; In about 1 to 3 lines.
+```
 
 ## Procedures en control flow
 
@@ -96,6 +107,13 @@ Verzamel dan de lijst en vraag of je ze moet toevoegen.
   (else ... alleen als het nodig is))
 ```
 
+## Gebruik van lokale helper functies
+
+- Gewone lokale waarden: let/let*.
+- Een kleine lokale helper: (let ((helper (λ (...) ...))) ...) is prima.
+- Een omvangrijke lokale helper die echt bij één closure hoort: een interne (define (helper ...) ...) is juist duidelijker en toegestaan.
+
+
 ## Mate van abstractie vs leesbaarheid
 
 Liever concreet dan abstract.