Guide - JSDoc

För att ytterligare öka läsbarheten av din kod är det viktigt att du använder kommentarer för att exempelvis tala om vad en funktion gör, vad den accepterar för argument, och vad den returnerar. Detta blir extra viktigt i ett löst typat språk, så som JavaScript.

Ett av kursens mål är:

Efter avslutad kurs ska studenten kunna dokumentera källkod.

Olika språk har olika "defacto standarder" för att dokumentera koden. För JavaScript är det JSDoc. Du kan läsa om grunderna direkt i dokumentationen.

Att du ska lära dig att dokumentera källkoden betyder dock inte att du måste kunna just JSDoc utantill, utan snarare att du ska lära dig förstå nyttan av och kunna, för kursens behov, dokumentera din källkod.

Denna guide kommer att lista ett antal exempel från vilka du uppmanas plocka, för stunden, lämpliga kommentarer.

Om du använder Visual Studio Code så har den inbyggt stöd för JSDoc.

Det som dokumenteras i kursen är:

  • Funktioner
  • Moduler
  • Klasser och dess medlemmar (används senare i kursen)
När du skriver JSDoc-kommentarer är det extra viktigt att tänka på att
  • skriva på engelska.
  • använda fullständiga meningar.
  • avsluta meningarna med en . (punkt).
  • inte dokumentera i efterhand.

Anledningen till att du inte vill dokumentera i efterhand är att du då inte kan dra lika mycket nytta av dina JSDoc-kommentarer. Om du dokumenterar innan du skriver koden helt färdig tvingas du tänka igenom uppgiften på ett strukturerat sätt. Vad ska funktionen göra? Vilka parametrar behövs? Vad är det som ska returneras?

Genom att dokumentera i förhand kan också verktyg så som Visual Studio Code, dra nytta av JSDoc-kommentarerna och ge dig en bättre upplevelse.

Funktioner

‌‌‌‌‌

Typer

Vanligt förekommande datatyper som kan användas som parameter eller returvärde:

  • number - Ett tal

  • string - En sträng

  • boolean - Ett booleskt värde

  • number[] - En array av tal

  • string[] - En array av strängar

  • boolean[] - En array av booleska värden

  • Player - En egendefinierad typ

Defaultvärden

‌‌‌‌‌

Moduler

En modul dokumenteras genom att inleda källkoden med en JSDoc-kommentar liknande

‌‌‌‌‌

Läs mer om att dokumentera moduler i dokumentationen.

Klasser

T.B.A

Läs mer om att dokumentera klasser i dokumentationen.