✍️ Commentaar in code is nog niet zo’n slecht idee. 🚀

💡 Heel veel jaren terug introduceerde een collega me in het concept “self-documenting code”: Het kiezen van namen voor functies en variabelen zodat uitleg in commentaar niet nodig is. We vonden het een briljante uitvinding.

Daarna heb ik geleerd om commentaar juist wel te gebruiken om toe te voegen wat er niet al in de code staat. Dus niet meer melden dat het een class of functie is, en vooral extra context voor beter begrip toevoegen. 🦄

🫣 Vervolgens heb ik door schade en schande ontdekt dat misschien wel het meest belangrijke “commentaar” bestaat uit documentatie van de structuur en intenties van de software als geheel. Dus het ontwerp of de architectuur die tijdens het bouwen op kladjes of het whiteboard staat, dan wel in je hoofd zit.

Dus doe jezelf, nieuwe teamleden (en jouw AI assistent) een plezier, en schrijf eindelijk eens de gedachten achter de code op. 🌈