Privacy & Cookies
Werken bijKennis | blogs | eventsContact
Naar kennisoverzicht

Bugs documenteren: een ode aan de SSCCE-methode

Als je al een tijdje in softwareland rondloopt, ken je de frustratie wel: een bug-report dat net zo helder is als een regenachtige maandagmorgen. "De knop werkt niet meer" of "Er gaat iets fout bij het opslaan" – bedenk daar maar eens iets voor. Alsof je een lek in een opblaasboot moet vinden terwijl je al in het midden van de oceaan dobbert.

Laat ik je vertellen, als je ooit bij iemand een paniekaanval hebt veroorzaakt met een vaag bug-report, je bent niet alleen. Maar er is hoop! Vandaag wil ik het hebben over een beproefde methode om bugs beter te documenteren: de SSCCE-methode. Deze methode helpt je om heldere, reproduceerbare en efficiënt op te lossen bug-reports te maken.

Wat is een SSCCE?

SSCCE staat voor:

  1. Short: Houd het voorbeeld kort en to the point. Niemand heeft zin om door duizend regels code te waden om een klein probleem te begrijpen.
  2. Self-Contained: Zorg dat het voorbeeld volledig op zichzelf staat. Geen afhankelijkheden van je 40 bibliotheken, geheime API-sleutels of de stand van de maan.
  3. Correct: Het voorbeeld moet de bug consistent reproduceren. Dus geen "soms werkt het wel, soms niet". Wees als een vastberaden detective.
  4. Compilable: De code moet zonder gedoe te compileren of uit te voeren zijn. Niemand houdt van een error bij het debuggen van een error.

Example (Voorbeeld): Het voorbeeld moet precies laten zien waar het probleem zit. Niet een hele applicatie met vijf tabbladen en acht vensters, maar dat ene kleine stukje dat faalt. Kortom, maak een voorbeeld dat direct laat zien waar de schoen wringt, zonder extra franje.

Waarom is SSCCE zo krachtig?

Stel je voor dat je je collega vraagt om je auto te repareren en je zegt alleen: "Hij doet raar." Dat schiet niet op. Maar als je zegt: "De motor slaat af wanneer ik de koppeling indruk tijdens het schakelen naar de tweede versnelling", dan kan je collega tenminste gericht zoeken.

Een goed gedocumenteerde bug werkt precies zo. Een SSCCE geeft je team een duidelijk, reproduceerbaar probleem. Hierdoor:

  • Verspil je minder tijd aan het zoeken naar de bug.
  • Voorkom je miscommunicatie over wat er nou precies fout gaat.
  • Help je jezelf door logisch na te denken over het probleem. Soms kom je tijdens het maken van een SSCCE al zelf achter de oplossing!

Een compleet praktijkvoorbeeld

Stel, je hebt een bug waarbij een knop in je webapplicatie niet reageert. Een goed bug-report bevat de context en een duidelijk voorbeeld:

  1. Wat was je aan het doen?
    Ik probeerde een formulier in te vullen en op de opslaan-knop te klikken om mijn wijzigingen op te slaan.
  2. In welke context gebeurde dit?
  • Browser: Google Chrome 120.0.6099.199
  • Besturingssysteem: Windows 11
  • Applicatieversie: 2.3.4
  • Gebruikte account-rol: Beheerder
  1. Wat verwachtte je te zien?
    Na het klikken op de opslaan-knop verwachtte ik een bevestigingsmelding dat mijn wijzigingen waren opgeslagen.
  2. Wat was het werkelijke resultaat?
    De knop reageerde niet en er verscheen geen bevestigingsmelding. In de browserconsole zag ik de volgende foutmelding:

Uncaught TypeError: Cannot read properties of undefined (reading 'submit')

    at HTMLButtonElement.<anonymous> (script.js:42)
  1. SSCCE voorbeeldcode

<!DOCTYPE html>

<html>

<head>

    <title>Bug Voorbeeld</title>

    <script>

        function saveForm() {

            const form = document.getElementById("myForm");

            form.submit(); // Hier gaat het mis als 'form' undefined is

        }

    </script>

</head>

<body>

    <form id="myForm">

        <input type="text" name="name" value="Jan">

        <button id="saveButton" onclick="saveForm()">Opslaan</button>

    </form>

</body>

</html>
  1. Mogelijke oplossing

Controleer of het element met id="myForm" correct geladen wordt voordat saveForm wordt aangeroepen.

Conclusie

Een goed bug-report is goud waard. Niet alleen bespaar je tijd voor jezelf en je team, maar je voorkomt ook dat mensen je ooit nog aankijken met die blik van "Wat bedoel je hier nou mee?". Dus de volgende keer dat je een bug tegenkomt, neem een paar extra minuten om een SSCCE te maken. Je toekomstige zelf (en je collega’s) zullen je erg dankbaar zijn.

En wie weet? Misschien bespaart het je die extra kop koffie die je anders nodig had om kalm te blijven tijdens een debugging-marathon.

Happy adventuring!

Referentie: https://www.sccce.org

Verder lezen